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
yperfield
. - 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
ywith
. - 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
estrue
) -
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
estrue
) -
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:
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:
¿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:
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
}
}