Cómo funcionan los documentos de diseño

IBM® Cloudant® for IBM Cloud® lee campos y valores específicos de los documentos de diseño como funciones. Los documentos de diseño se utilizan para construir índices y validar actualizaciones.

Cada documento de diseño define los índices particionados o globales, que se controlan mediante el campo options.partitioned. Un índice particionado solo permite consultas sobre una única partición de datos en una base de datos particionada. Un índice global permite consultar todos los datos dentro de una base de datos, a un coste de latencia y rendimiento sobre un índice particionado.

Creación o actualización de un documento de diseño

Método: PUT /$DATABASE/_design/$DDOC
Solicitud: JSON de la información del documento de diseño.
Respuesta: Estado JSON.
Roles permitidos: _admin

Para crear un documento de diseño, cárguelo en la base de datos especificada.

En estos ejemplos, $VARIABLES puede hacer referencia a documentos estándar o de diseño. Para distinguir entre ellos, los documentos estándar tienen un _id indicado por $DOCUMENT_ID, mientras que los documentos de diseño tienen un _id indicado por $DDOC.

El ID de un documento de diseño nunca incluye una clave de partición, independientemente del tipo de particionamiento de la base de datos. La clave de la partición no se incluye porque los índices que se incluyen dentro de un documento de diseño se aplican a todas las particiones de una base de datos particionada.

Si se actualiza un documento de diseño, IBM Cloudant suprime los índices de la versión anterior y vuelve a crear el índice desde cero. Si necesita 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.

La estructura de un documento de diseño incluye las siguientes partes:

_id

ID de documento de diseño. Este ID siempre tiene el prefijo _design y nunca incluye una clave de partición, independientemente del tipo de particionamiento de bases de datos.

_rev

Revisión de documento de diseño.

Opciones

Contiene opciones para este documento de diseño.

Particionado (opcional, booleano): Determina si este documento de diseño describe índices particionados o globales. Para obtener más información, consulte el campo options.partitioned.

Vistas (opcional)

Un objeto que describe las vistas de MapReduce.

   `Viewname`
  :  (One for each view) - View Definition.

       Map
         :  Map Function for the view.

Reducir (opcional)

Función Reducir para la vista.

Índices (opcional)

Objeto que describe los índices de búsqueda.

Nombre de índice: (Uno por cada índice)- Definición del índice.
Analizador: Objeto que describe el analizador que se va a utilizar o un objeto con los siguientes campos:

Nombre

Nombre del analizador. Los valores válidos son standard, email, keyword, simple, whitespace, classic y perfield.

Palabras vacías (opcional)

Una matriz de palabras vacías. Las palabras de detención son palabras que no se deben indexar. Si se especifica esta matriz, modifica la lista predeterminada de palabras de detención. La lista predeterminada de palabras de detención depende del analizador. El analizador estándar incluye las siguientes palabras de detención: a, an, and, are, as, at, be, but, by, for, if, in, into, is, it, no, not, of, on, or, such, that, the, their, then, there, these, they, this, to, was, will y with.

Valor predeterminado (para el analizador por campo)

Idioma predeterminado a utilizar si no se especifica ningún idioma para el campo.

Campos (para el analizador por campo): Objeto que especifica el idioma que se debe utilizar para analizar cada campo del índice. Los nombres de campo del objeto corresponden a nombres de campo del índice, es decir, el primer parámetro de la función de índice. Los valores de los campos son los idiomas que se utilizarán, por ejemplo, english.
Índice: Función que se encarga de la indexación.

Filtros (opcionales, no permitidos cuando partitioned es true)

Funciones de filtro.

Nombre de la función (uno para cada función): Definición de función.

Validate_doc_update (opcional, no permitido cuando partitioned es true)

Actualizar función de validación.

El campo `options.partitioned`

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

Este campo incluye los valores siguientes:

Valores para el campo options.partitioned
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:

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

Copia de un documento de diseño

Puede copiar la versión más reciente de un documento de diseño en un nuevo documento especificando el documento base y el documento de destino. La copia se solicita con el método de solicitud COPY.

COPY is a nonstandard HTTP command.

El ejemplo siguiente solicita que IBM Cloudant copie el documento de diseño allusers en el nuevo documento de diseño copyOfAllusers y genere una respuesta que incluya el ID y la revisión del nuevo documento.

La copia de un documento de diseño no reconstruye automáticamente los índices de vista. Al igual que otras vistas, estas vistas se vuelven a crear la primera vez que accede a la nueva vista.

Consulte el siguiente mandato de ejemplo para copiar un documento de diseño mediante HTTP:

COPY $SERVICE_URL/$DATABASE/_design/$DDOC HTTP/1.1
Content-Type: application/json
Destination: _design/$COPY_OF_DDOC

Consulte el siguiente mandato de ejemplo para copiar un documento de diseño:

Los IBM Cloudant SDKs actualmente no soportan el método HTTP COPY.

curl "$SERVICE_URL/users/_design/allusers" \
	-X COPY \
	-H "Content-Type: application/json" \
	-H "Destination: _design/copyOfAllusers"

Consulte la siguiente respuesta de ejemplo a la solicitud de copia:

{
  "ok": true,
  "id": "_design/copyOfAllusers",
  "rev": "1-9c65296036141e575d32ba9c034dd3ee"
}

La estructura del mandato copy

Método: COPY /$DATABASE/_design/$DDOC
Solicitud: Ninguna.
Respuesta: JSON que describe el nuevo documento y la revisión.
Roles permitidos: _design

Argumentos de consulta

Argumento

rev

Descripción: Revisión de la que copiar.
Opcional: Sí.
Tipo: Serie.

Cabeceras HTTP

Cabecera

Destination

Descripción: Documento de destino (y revisión opcional)
Opcional: Núm.

El documento de diseño de origen se especifica en la línea de solicitud, mientras que la cabecera HTTP Destination de la solicitud especifica el documento de destino.

Copia desde una revisión específica

Para copiar desde una versión específica, añada el argumento rev a la serie de consulta.

El nuevo documento de diseño se crea utilizando la revisión especificada del documento de origen.

Consulte el siguiente mandato de ejemplo para copiar una revisión específica del documento de diseño mediante HTTP:

COPY $SERVICE_URL/$DATABASE/_design/$DDOC?rev=$REV HTTP/1.1
Content-Type: application/json
Destination: _design/$COPY_OF_DDOC

Consulte el siguiente mandato de ejemplo para copiar una revisión específica del documento de diseño mediante la línea de mandatos:

curl "$SERVICE_URL/users/_design/allusers?rev=1-e23b9e942c19e9fb10ff1fde2e50e0f5" \
	-X COPY \
	-H "Content-Type: application/json" \
	-H "Destination: _design/copyOfAllusers"

Copia en un documento de diseño existente

Para sobrescribir o copiar en un documento existente, especifique la serie de revisión actual para el documento de destino con el parámetro rev en la serie de cabecera HTTP Destination.

Consulte el siguiente mandato de ejemplo para sobrescribir una copia existente del documento de diseño mediante HTTP:

COPY $SERVICE_URL/$DATABASE/_design/$DDOC
Content-Type: application/json
Destination: _design/$COPY_OF_DDOC?rev=$REV

Consulte el siguiente mandato de ejemplo para sobrescribir una copia existente del documento de diseño mediante la línea de mandatos:

curl "$SERVICE_URL/users/_design/allusers" \
	-X COPY \
	-H "Content-Type: application/json" \
	-H "Destination: _design/copyOfAllusers?rev=1-9c65296036141e575d32ba9c034dd3ee"

El valor de retorno es el ID y la nueva revisión del documento copiado.

Consulte la siguiente respuesta de ejemplo para sobrescribir una copia existente del documento de diseño:

{
  "id" : "_design/copyOfAllusers",
  "rev" : "2-55b6a1b251902a2c249b667dab1c6692"
}

Supresión de un documento de diseño

Puede suprimir un documento de diseño existente. Cuando se suprime un documento de diseño también se suprimen todos los índices de vista asociados y se recupera el espacio correspondiente en disco para los índices en cuestión.

Para suprimir un documento de diseño correctamente, debe especificar la revisión actual del documento de diseño con el argumento de consulta rev.

Consulte el siguiente mandato de ejemplo para suprimir un documento de diseño mediante HTTP:

DELETE $SERVICE_URL/$DATABASE/_design/$DDOC?rev=$REV HTTP/1.1

Consulte los siguientes ejemplos para suprimir un documento de diseño:

curl "$SERVICE_URL/users/_design/allusers?rev=2-21314508552eceb0e3012429d04575da" -X DELETE

from ibmcloudant.cloudant_v1 import CloudantV1

service = CloudantV1.new_instance()

response = service.delete_design_document(
  db='users',
  ddoc='allusers',
  rev='2-21314508552eceb0e3012429d04575da'
).get_result()

print(response)

import com.ibm.cloud.cloudant.v1.Cloudant;
import com.ibm.cloud.cloudant.v1.model.DeleteDesignDocumentOptions;
import com.ibm.cloud.cloudant.v1.model.DocumentResult;

Cloudant service = Cloudant.newInstance();

DeleteDesignDocumentOptions designDocumentOptions =
    new DeleteDesignDocumentOptions.Builder()
        .db("users")
        .ddoc("allusers")
        .rev("2-21314508552eceb0e3012429d04575da")
        .build();

DocumentResult response =
    service.deleteDesignDocument(designDocumentOptions).execute()
        .getResult();

System.out.println(response);

const { CloudantV1 } = require('@ibm-cloud/cloudant');

const service = CloudantV1.newInstance({});

service.deleteDesignDocument({
  db: 'users',
  ddoc: 'allusers',
  rev: '2-21314508552eceb0e3012429d04575da'
}).then(response => {
  console.log(response.result);
});

deleteDesignDocumentOptions := service.NewDeleteDesignDocumentOptions(
  "users",
  "allusers",
)
deleteDesignDocumentOptions.SetRev("2-21314508552eceb0e3012429d04575da")

documentResult, response, err := service.DeleteDesignDocument(deleteDesignDocumentOptions)
if err != nil {
  panic(err)
}

b, _ := json.MarshalIndent(documentResult, "", "  ")
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"
)

Consulte la siguiente respuesta de ejemplo que incluye el ID y la revisión del documento suprimido:

{
  "id": "_design/allusers",
  "ok": true,
  "rev": "3-7a05370bff53186cb5d403f861aca154"
}

La estructura del mandato delete

Método: DELETE /db/_design/$DDOC
Solicitud: Ninguna.
Respuesta: JSON del documento de diseño suprimido.
Roles permitidos: _design

Argumentos de consulta

Argumento

rev

Descripción: Revisión actual del documento para la validación.
Opcional: Sí, si If-Match la cabecera existe.
Tipo: Serie.

Cabeceras HTTP

Cabecera

If-Match

Descripción: Revisión actual del documento para la validación.
Opcional: Sí, si rev existe el argumento de consulta.

Vistas

Un uso importante de los documentos de diseño es para crear vistas. Para obtener más información sobre la creación de vistas, consulte Vistas (MapReduce).

Índices

Todas las consultas operan sobre índices predefinidos que se definen en documentos de diseño. Estos índices están definidos en la lista siguiente:

Por ejemplo, para crear un documento de diseño que se utilice para búsquedas, debe asegurarse de que se cumplan estas dos condiciones:

Ha definido el documento como un documento de diseño al iniciar el _id con _design/.
Ha creado un índice de búsqueda en el documento en el que ha actualizado el documento con el campo adecuado o creado un nuevo documento que incluye el índice de búsqueda.

En cuanto exista el documento de diseño del índice de búsqueda y se cree el índice, puede realizar consultas con el mismo.

Notas generales sobre funciones en documentos de diseño

Las funciones en los documentos de diseño se ejecutan en varios nodos para cada documento y se pueden ejecutar varias veces. Para evitar incoherencias, tienen que ser idempotentes, lo que significa que deben comportarse de forma idéntica cuando se ejecutan varias veces o en diferentes nodos. En particular, no debe utilizar funciones que generen números aleatorios o que devuelvan la hora actual.

Funciones de filtro (filter)

Los documentos de diseño con options.partitioned establecido en true no pueden contener un campo filters.

Las funciones de filtro son documentos de diseño que filtran el canal de información de cambios. Funcionan aplicando pruebas a cada uno de los objetos incluidos en el canal de información de cambios.

Si alguna de las pruebas de función falla, el objeto se "elimina" o se "filtra" del canal de información. Si la función devuelve un resultado true cuando se aplica a un cambio, el cambio permanece en el canal de información. Es decir, las funciones de filtro "eliminan" o "ignoran" los cambios que no desea supervisar.

Las funciones de filtro también se pueden utilizar para modificar una tarea de réplica.

Las funciones de filtro requieren dos argumentos: doc y req.

El argumento doc representa el documento que se prueba para el filtrado.

El argumento req incluye más información sobre la solicitud. Con este argumento, puede crear funciones de filtro que sean más dinámicas porque se basan en varios factores, como por ejemplo los parámetros de consulta o el contexto de usuario.

Por ejemplo, puede controlar aspectos de las pruebas de función de filtro mediante valores dinámicos que se proporcionan como parte de la solicitud HTTP. Sin embargo, en muchos casos de uso de filtro, solo se utiliza el parámetro doc.

Consulte el siguiente documento de diseño de ejemplo que incluye una función de filtro:

{
	"_id":"_design/example_design_doc",
	"filters": {
		"example_filter": "function (doc, req) { ... }"
	}
}

Consulte el ejemplo siguiente de una función de filtro:

function(doc, req){
	// we need only `mail` documents
	if (doc.type != 'mail'){
		return false;
	}
	// we're interested only in `new` ones
	if (doc.status != 'new'){
		return false;
	}
	return true; // passed!
}

Cambia las funciones de filtro de canal de información

Para aplicar una función de filtro al canal de información de cambios, incluya el parámetro filter en la consulta _changes, proporcionando el nombre del filtro que se va a utilizar.

Véase el siguiente ejemplo de una función de filtro que se aplica a una _changes consulta mediante HTTP:

POST $SERVICE_URL/$DATABASE/_changes?filter=$DDOC/$FILTER_FUNCTION HTTP/1.1

Consulte los siguientes ejemplos de una función de filtro aplicada a una consulta de _changes:

curl -X POST "$SERVICE_URL/orders/_changes?filter=example_design_doc/example_filter" -H "Content-Type: application/json" -d '{}'

from ibmcloudant.cloudant_v1 import CloudantV1

service = CloudantV1.new_instance()

response = service.post_changes(
  db='orders',
  filter='example_design_doc/example_filter'
).get_result()

print(response)

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")
    .filter("example_design_doc/example_filter")
    .build();

ChangesResult response =
    service.postChanges(changesOptions).execute()
        .getResult();

System.out.println(response);

const { CloudantV1 } = require('@ibm-cloud/cloudant');

const service = CloudantV1.newInstance({});

service.postChanges({
  db: 'orders',
  filter: 'example_design_doc/example_filter'
}).then(response => {
  console.log(response.result);
});

postChangesOptions := service.NewPostChangesOptions(
  "$DATABASE",
)
postChangesOptions.SetFilter("example_design_doc/example_filter")

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

Argumento `req` de la función de filtro

El argumento req le proporciona acceso a aspectos de la solicitud HTTP mediante la propiedad query.

Consulte el ejemplo siguiente de suministro de un argumento req mediante HTTP:

GET $SERVICE_URL/$DATABASE/_changes?filter=$DDOC/$FILTER_FUNCTION&status=new HTTP/1.1

Consulte el siguiente ejemplo de suministro de un argumento de req:

El IBM Cloudant SDKs actualmente no admiten status opción para _changes solicitud.

curl "$SERVICE_URL/$DATABASE/_changes?filter=$DDOC/$FILTER_FUNCTION&status=new"

Consulte el siguiente filtro de ejemplo mediante un argumento req suministrado:

function(doc, req){
	// we need only `mail` documents
	if (doc.type != 'mail'){
		return false;
	}
	// we're interested only in `new` ones
	if (doc.status != req.query.status){
		return false;
	}
	return true; // passed!
}

Funciones de filtro (filter) predefinidas

Hay varias funciones de filtro predefinidas disponibles:

_design: Acepta sólo los cambios en los documentos de diseño.
_doc_ids: Acepta sólo los cambios para los documentos cuyo ID se especifica en el parámetro doc_ids o en el documento JSON proporcionado.
_selector: Sólo acepta cambios para documentos que coincidan con un selector especificado que se define utilizando la misma sintaxis de selector que se describe en la sección Solicitud, que se utiliza para _find.
_view: Con esta función, puede utilizar una función de correlación existente como filtro.

El filtro `_design`

El filtro _design solo acepta cambios para documentos de diseño dentro de la base de datos solicitada.

El filtro no requiere ningún argumento.

Se muestran los cambios correspondientes a todos los documentos de diseño dentro de la base de datos.

Consulte la siguiente aplicación de ejemplo del filtro _design mediante HTTP:

POST /$DATABASE/_changes?filter=_design HTTP/1.1

Consulte las siguientes aplicaciones de ejemplo del filtro de _design:

curl -X POST "$SERVICE_URL/orders/_changes?filter=_design" -H "Content-Type: application/json" -d '{}'

from ibmcloudant.cloudant_v1 import CloudantV1

service = CloudantV1.new_instance()

response = service.post_changes(
  db='orders',
  filter='_design'
).get_result()

print(response)

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")
    .filter("_design")
    .build();

ChangesResult response =
    service.postChanges(changesOptions).execute()
        .getResult();

System.out.println(response);

const { CloudantV1 } = require('@ibm-cloud/cloudant');

const service = CloudantV1.newInstance({});

service.postChanges({
  db: 'orders',
  filter: '_design'
}).then(response => {
  console.log(response.result);
});

postChangesOptions := service.NewPostChangesOptions(
  "$DATABASE",
)
postChangesOptions.SetFilter("_design")

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

Consulte la siguiente respuesta de ejemplo (abreviada) después de aplicar el filtro _design:

{
  ...
  "results":[
    {
      "changes":[
        {
          "rev":"10-304...4b2"
        }
      ],
      "id":"_design/ingredients",
      "seq":"8-g1A...gEo"
    },
    {
      "changes":[
        {
          "rev":"123-6f7...817"
        }
      ],
      "deleted":true,
      "id":"_design/cookbook",
      "seq":"9-g1A...4BL"
    },
    ...
  ]
}

El filtro `_doc_ids`

El filtro _doc-ids solo acepta cambios para los documentos con los ID especificados. Los ID se especifican en un parámetro doc_ids o dentro de un documento JSON que se proporciona como parte de la solicitud original.

Consulte la siguiente aplicación de ejemplo del filtro _doc_ids mediante HTTP:

POST $SERVICE_URL/$DATABASE/_changes?filter=_doc_ids HTTP/1.1

Consulte las siguientes aplicaciones de ejemplo del filtro de _doc_ids:

curl -X POST "$SERVICE_URL/orders/_changes?filter=_doc_ids" -H "Content-Type: application/json" -d '{"doc_ids": ["ExampleID"]}'

from ibmcloudant.cloudant_v1 import CloudantV1

service = CloudantV1.new_instance()

response = service.post_changes(
  db='orders',
  filter='_doc_ids',
  doc_ids=['ExampleID']
).get_result()

print(response)

import java.util.Arrays;

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")
    .filter("_doc_ids")
    .docIds(Arrays.asList("ExampleID"))
    .build();

ChangesResult response =
    service.postChanges(changesOptions).execute()
        .getResult();

System.out.println(response);

const { CloudantV1 } = require('@ibm-cloud/cloudant');

const service = CloudantV1.newInstance({});

service.postChanges({
  db: 'orders',
  filter: '_doc_ids',
  docIds: ['ExampleID']
}).then(response => {
  console.log(response.result);
});

postChangesOptions := service.NewPostChangesOptions(
  "$DATABASE",
)
postChangesOptions.SetFilter("_doc_ids")
postChangesOptions.SetDocIds([]string{"ExampleID"})

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

Consulte el siguiente documento JSON de ejemplo que muestra los ID de documento que se van a comparar durante el filtrado:

{
  "doc_ids": [
    "ExampleID"
  ]
}

Consulte la siguiente respuesta de ejemplo (abreviada) después de filtrar por _docs_ids:

{
  "last_seq":"5-g1A...o5i",
  "pending":0,
  "results":[
    {
      "changes":[
        {
          "rev":"13-bcb...29e"
        }
      ],
      "id":"ExampleID",
      "seq":"5-g1A...HaA"
    }
  ]
}

El filtro `_selector`

El filtro _selector sólo acepta cambios para documentos que coincidan con un selector especificado, que se define utilizando la misma sintaxis de selector que se utiliza para _find.

Para ver más ejemplos que muestran el uso de este filtro, consulte la información sobre el selector de sintaxis.

Consulte la siguiente aplicación de ejemplo del filtro _selector mediante HTTP:

POST $SERVICE_URL/$DATABASE/_changes?filter=_selector HTTP/1.1

Consulte las siguientes aplicaciones de ejemplo del filtro de _selector:

curl -X POST "$SERVICE_URL/orders/_changes?filter=_selector" -H "Content-Type: application/json" -d '{"selector": {"_id": { "$regex": "^_design/"}}}'

from ibmcloudant.cloudant_v1 import CloudantV1

service = CloudantV1.new_instance()

response = service.post_changes(
  db='orders',
  filter='_selector',
  selector={'_id': { '$regex': '^_design/'}}
).get_result()

print(response)

import java.util.HashMap;
import java.util.Map;

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

Map<String, Object> selector = new HashMap<String, Object>();
selector.put("_id", new HashMap<>().put("$regex", "^_design/"));

PostChangesOptions changesOptions = new PostChangesOptions.Builder()
    .db("orders")
    .filter("_selector")
    .selector(selector)
    .build();

ChangesResult response =
    service.postChanges(changesOptions).execute()
        .getResult();

System.out.println(response);

const { CloudantV1 } = require('@ibm-cloud/cloudant');

const service = CloudantV1.newInstance({});

service.postChanges({
    db: 'animaldb',
    filter: '_selector',
    selector: {"_id": { "$regex": "^_design/"}},
  }).then(response => {
    console.log(response.result);
  });

postChangesOptions := service.NewPostChangesOptions(
  "$DATABASE",
)
postChangesOptions.SetFilter("_selector")
postChangesOptions.SetSelector(map[string]interface{}{
  "_id": map[string]string{ "$regex": "^_design/"}})

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

Consulte el siguiente documento JSON de ejemplo que incluye la expresión del selector que se utilizará durante el filtrado:

{
  "selector":{
    "_id":{
      "$regex":"^_design/"
    }
  }
}

Consulte la siguiente respuesta de ejemplo (abreviada) después de filtrar utilizando un selector:

{
  "last_seq":"11-g1A...OaA",
  "pending":0,
  "results":[
    {
      "changes":[
        {
          "rev":"10-304...4b2"
        }
      ],
      "id":"_design/ingredients",
      "seq":"8-g1A...gEo"
    },
    {
      "changes":[
        {
          "rev":"123-6f7...817"
        }
      ],
      "deleted":true,
      "id":"_design/cookbook",
      "seq":"9-g1A...4BL"
    },
    {
      "changes":[
        {
          "rev":"6-5b8...8f3"
        }
      ],
      "deleted":true,
      "id":"_design/meta",
      "seq":"11-g1A...Hbg"
    }
  ]
}

El filtro `_view`

Mediante el filtro _view puede utilizar una función de correlación existente como filtro.

La función de correlación puede emitir salida como el resultado del proceso de un documento específico. Cuando se da esta situación, el filtro tiene en cuenta el documento que está permitido y lo incluye en la lista de documentos que ha cambiado.

Consulte la siguiente aplicación de ejemplo del filtro _view mediante HTTP:

POST $SERVICE_URL/$DATABASE/_changes?filter=_view&view=$DDOC/$VIEW_NAME HTTP/1.1

Consulte las siguientes aplicaciones de ejemplo del filtro de _view:

curl -X POST "$SERVICE_URL/animaldb/_changes?filter=_view&view=views101/latin_name" -H "Content-Type: application/json" -d '{}'

from ibmcloudant.cloudant_v1 import CloudantV1

service = CloudantV1.new_instance()

response = service.post_changes(
  db='animaldb',
  filter='_view',
  view='views101/latin_name'
).get_result()

print(response)

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("animaldb")
    .filter("_vew")
    .view("views101/latin_name")
    .build();

ChangesResult response =
    service.postChanges(changesOptions).execute()
        .getResult();

System.out.println(response);

const { CloudantV1 } = require('@ibm-cloud/cloudant');

const service = CloudantV1.newInstance({});

service.postChanges({
  db: 'animaldb',
  filter: '_view',
  view: 'views101/latin_name'
}).then(response => {
  console.log(response.result);
});

postChangesOptions := service.NewPostChangesOptions(
  "animaldb",
)
postChangesOptions.SetFilter("_view")
postChangesOptions.SetView("views101/latin_name")

changesResult, _, err := service.PostChanges(postChangesOptions)
if err != nil {
fmt.Println(err)
}

b, _ := json.MarshalIndent(changesResult, "", "  ")
fmt.Println(string(b))

Consulte la siguiente respuesta de ejemplo (abreviada) después de filtrar utilizando una función de correlación:

{
  "last_seq": "5-g1A...o5i",
  "results": [
    {
      "changes": [
        {
          "rev": "13-bcb...29e"
        }
      ],
      "id": "ExampleID",
      "seq":  "5-g1A...HaA"
    }
  ]
}

Validadores de actualización

Los documentos de diseño con options.partitioned establecido en true no pueden contener un campo validate_doc_update.

Los validadores de actualización determinan si un documento se debe escribir en disco cuando se intenta realizar inserciones y actualizaciones. No requieren una consulta porque se ejecutan implícitamente durante este proceso. Si se rechaza un cambio, el validador de actualización responde con un error personalizado.

Los validadores de actualización requieren cuatro argumentos:

Argumentos para el validador de actualización
Argumento	Finalidad
`newDoc`	La versión del documento que se ha pasado en la solicitud.
`oldDoc`	La versión del documento que hay actualmente en la base de datos o `null` si no existe ninguna.
`secObj`	El objeto de seguridad para la base de datos.
`userCtx`	Contexto sobre el usuario autenticado actualmente, como por ejemplo `name` y `roles`.

Los validadores de actualización no se aplican cuando un usuario administrador actualiza un documento de diseño. Esta práctica garantiza que los administradores nunca pueden bloquearse a sí mismos accidentalmente.

Consulte el siguiente documento de diseño de ejemplo con un validador de actualización:

{
	"_id": "_design/validator_example",
	"validate_doc_update": "function(newDoc, oldDoc, userCtx, secObj) { ... }"
}

Consulte el ejemplo siguiente de un validador de actualización:

function(newDoc, oldDoc, userCtx, secObj) {
	if (newDoc.address === undefined) {
		throw({forbidden: 'Document must have an address.'});
	}
}

Consulte la siguiente respuesta de ejemplo de un validador de actualización:

{
	"error": "forbidden",
	"reason": "Document must have an address."
}

Recuperación de información sobre un documento de diseño

Dos puntos finales le proporcionan más información sobre los documentos de diseño: _info y _search_info.

El punto final `_info`

El punto final _info devuelve información sobre un documento de diseño específico, incluido el índice de vista, el tamaño de índice de vista y el estado del documento de diseño y la información de índice de la vista asociada.

Método: GET /db/_design/$DDOC/_info
Solicitud: Ninguna
Respuesta: JSON que contiene la información del documento de diseño.
Roles permitidos: _reader

Consulte el ejemplo siguiente para recuperar información sobre el documento de diseño recipesdd desde dentro de la base de datos recipes mediante HTTP:

GET /recipes/_design/recipesdd/_info HTTP/1.1

Consulte los siguientes ejemplos de recuperación de información sobre el documento de diseño de recipesdd desde la base de datos de recipes:

curl "$SERVICE_URL/recipes/_design/recipesdd/_info"

getDesignDocumentInformationOptions := service.NewGetDesignDocumentInformationOptions(
  "recipes",
  "recipesdd",
)

designDocumentInformation, response, err := service.GetDesignDocumentInformation(getDesignDocumentInformationOptions)
if err != nil {
  panic(err)
}

b, _ := json.MarshalIndent(designDocumentInformation, "", "  ")
fmt.Println(string(b))

from ibmcloudant.cloudant_v1 import CloudantV1

service = CloudantV1.new_instance()

response = service.get_design_document_information(
  db='recipes',
  ddoc='recipesdd'
).get_result()

print(response)

import com.ibm.cloud.cloudant.v1.Cloudant;
import com.ibm.cloud.cloudant.v1.model.DesignDocumentInformation;
import com.ibm.cloud.cloudant.v1.model.GetDesignDocumentInformationOptions;

Cloudant service = Cloudant.newInstance();

GetDesignDocumentInformationOptions informationOptions =
    new GetDesignDocumentInformationOptions.Builder()
        .db("recipes")
        .ddoc("recipesdd")
        .build();

DesignDocumentInformation response =
    service.getDesignDocumentInformation(informationOptions).execute()
        .getResult();

System.out.println(response);

const { CloudantV1 } = require('@ibm-cloud/cloudant');

const service = CloudantV1.newInstance({});

service.getDesignDocumentInformation({
  db: 'recipes',
  ddoc: 'recipesdd'
}).then(response => {
  console.log(response.result);
});

La respuesta JSON incluye los siguientes campos individuales:

name

Nombre o ID del documento de diseño.

view_index

Índice de vista

compact_running: Indica si hay una rutina de compactación ejecutándose en la vista.
disk_size: Tamaño en bytes de la vista almacenada en disco.
language: Lenguaje que se utiliza para definir vistas.
purge_seq: Secuencia de depuración que se ha procesado.
signature: Firma MD5 de las vistas para el documento de diseño.
update_seq: Secuencia de actualización de la base de datos correspondiente que se ha indexado.
updater_running: Indica si la vista se está actualizando.
waiting_clients: Número de clientes que están a la espera de las vistas de este documento de diseño.
waiting_commit: Indica si la base de datos subyacente tiene confirmaciones pendientes que deben procesarse.

Consulte la siguiente respuesta de ejemplo en formato JSON:

{
	"name" : "recipesdd",
	"view_index": {
		"compact_running": false,
		"updater_running": false,
		"language": "javascript",
		"purge_seq": 10,
		"waiting_commit": false,
		"waiting_clients": 0,
		"signature": "fc65594ee76087a3b8c726caf5b40687",
		"update_seq": 375031,
		"disk_size": 16491
	}
}

El punto final `_search_info`

El punto final _search_info devuelve información sobre una búsqueda especificada que está definida en un documento de diseño específico.

Método: GET /db/_design/$DDOC/_search_info/yourSearch
Solicitud: Ninguna
Respuesta: JSON que contiene información sobre la búsqueda especificada.
Roles permitidos*: _reader

Consulte el ejemplo siguiente para obtener información sobre la búsqueda de description, que está definida en el documento de diseño de app almacenado en la base de datos foundbite, mediante HTTP:

GET /foundbite/_design/app/_search_info/description HTTP/1.1

Consulte los ejemplos siguientes para obtener información sobre el índice de búsqueda de description, que se define en el documento de diseño de app que se almacena en la base de datos de foundbite:

curl "$SERVICE_URL/foundbite/_design/app/_search_info/description"

from ibmcloudant.cloudant_v1 import CloudantV1

service = CloudantV1.new_instance()

response = service.get_search_info(
  db='foundbite',
  ddoc='app',
  index='description'
).get_result()

print(response)

import com.ibm.cloud.cloudant.v1.Cloudant;
import com.ibm.cloud.cloudant.v1.model.GetSearchInfoOptions;
import com.ibm.cloud.cloudant.v1.model.SearchInfoResult;

Cloudant service = Cloudant.newInstance();

GetSearchInfoOptions infoOptions =
    new GetSearchInfoOptions.Builder()
        .db("foundbite")
        .ddoc("app")
        .index("description")
        .build();

SearchInfoResult response =
    service.getSearchInfo(infoOptions).execute()
        .getResult();

System.out.println(response);

const { CloudantV1 } = require('@ibm-cloud/cloudant');

const service = CloudantV1.newInstance({});

service.getSearchInfo({
  db: 'foundbite',
  ddoc: 'app',
  index: 'description'
}).then(response => {
  console.log(response.result);
});

getSearchInfoOptions := service.NewGetSearchInfoOptions(
  "foundbite",
  "app",
  "description",
)

searchInfoResult, response, err := service.GetSearchInfo(getSearchInfoOptions)
if err != nil {
  panic(err)
}

b, _ := json.MarshalIndent(searchInfoResult, "", "  ")
fmt.Println(string(b))

La estructura JSON incluye los siguientes campos individuales:

name: Nombre o ID de la búsqueda en el documento de diseño.
search_index: El índice de búsqueda
pending_seq: El número de secuencia de cambios en la base de datos que ha alcanzado el índice Lucene, tanto en la memoria como en el disco.
doc_del_count: Número de documentos suprimidos en el índice.
doc_count: Número de documentos en el índice.
disk_size: El tamaño del índice en el disco, en bytes.
committed_seq: El número de secuencia de cambios en la base de datos que se han confirmado en el índice Lucene en el disco.

Consulte la siguiente respuesta de ejemplo en formato JSON:

{
  "name":"_design/app/description",
  "search_index":{
    "pending_seq":63,
    "doc_del_count":3,
    "doc_count":10,
    "disk_size":9244,
    "committed_seq":63
  }
}

Cómo funcionan los documentos de diseño

Creación o actualización de un documento de diseño

El campo options.partitioned

Copia de un documento de diseño

La estructura del mandato copy

Copia desde una revisión específica

Copia en un documento de diseño existente

Supresión de un documento de diseño

La estructura del mandato delete

Vistas

Índices

Notas generales sobre funciones en documentos de diseño

Funciones de filtro (filter)

Cambia las funciones de filtro de canal de información

Argumento req de la función de filtro

Funciones de filtro (filter) predefinidas

El filtro _design

El filtro _doc_ids

El filtro _selector

El filtro _view

Validadores de actualización

Recuperación de información sobre un documento de diseño

El punto final _info

El punto final _search_info

El campo `options.partitioned`

Argumento `req` de la función de filtro

El filtro `_design`

El filtro `_doc_ids`

El filtro `_selector`

El filtro `_view`

El punto final `_info`

El punto final `_search_info`