Como funcionam os documentos de design

O IBM® Cloudant® for IBM Cloud® lê campos e valores específicos de documentos de design como funções. Os documentos de design são usados para construir índices e validar atualizações.

Cada documento de design define os índices particionados ou globais, que são controlados pelo campo options.partitioned. Um índice particionado só permite consultas em uma única partição de dados em um banco de dados particionado. Um índice global permite consultas em todos os dados de um banco de dados, ao custo de latência e do rendimento, em um índice particionado.

Criando ou atualizando um documento de design

Método: PUT /$DATABASE/_design/$DDOC
Solicitação: JSON com as informações do documento de projeto.
Resposta: Status JSON.
Funções permitidas: _admin

Para criar um documento de design, faça seu upload para o banco de dados especificado.

Nestes exemplos, $VARIABLES pode referir-se a documentos padrão ou de design. Para distinguir entre eles, os documentos padrão têm um _id indicado por $DOCUMENT_ID, enquanto os documentos de design têm um _id indicado por $DDOC.

O ID de um documento de design nunca inclui uma chave de partição, independentemente do tipo de particionamento do banco de dados. A chave de partição não está incluída porque os índices que estão incluídos dentro de um documento de design aplicam-se a todas as partições em um banco de dados particionado.

Se um documento de design for atualizado, o IBM Cloudant excluirá os índices da versão anterior e recriará o índice do zero. Se for necessário mudar um documento de design para um banco de dados maior, confira o Guia de gerenciamento de documentos de design.

A estrutura de um documento de design inclui as partes a seguir:

_id

ID do documento de design. Esse ID é sempre prefixado com _design e nunca inclui uma chave de partição, independentemente do tipo de particionamento de banco de dados.

_rev

Revisão de documento de design.

Opções

Contém opções para este documento de design.

Particionado (opcional, booleano): Determina se este documento de projeto descreve índices particionados ou globais. Para obter mais informações, consulte O campo options.partitioned.

Visualizações (opcional)

Um objeto que descreve as visualizações MapReduce.

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

Reduzir (opcional)

Função Reduzir para a visualização.

Índices (opcional)

Um objeto que descreve índices de pesquisa.

Nome do índice

(Um para cada índice) — Definição do índice.

Analisador: Objeto que descreve o analisador a ser utilizado ou um objeto com os seguintes campos:

Nome

Nome do analisador. Os valores válidos são standard, email, keyword, simple, whitespace, classic e perfield.

Stopwords (opcional)

Uma matriz de palavras comuns. Palavras vazias são palavras que não devem ser indexadas. Se essa matriz for especificada, ela substituirá a lista padrão de palavras vazias. A lista padrão de palavras vazias depende do analisador. O analisador padrão inclui a lista de palavras vazias a seguir: 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 e with.

Padrão (para o analisador de campo)

Linguagem padrão para usar se nenhuma linguagem for especificada para o campo.

Campos (para o analisador de campo): Um objeto que especifica qual idioma utilizar para analisar cada campo do índice. Os nomes de campo no objeto correspondem aos nomes de campo no índice, ou seja, o primeiro parâmetro da função de índice. Os valores dos campos são os idiomas a serem usados, por exemplo, english.
Index: Função que lida com a indexação.

Filtros (opcionais; não permitidos quando partitioned é true``)

Funções do filtro.

Nome da função (um para cada função): Definição de função.

Validate_doc_update (opcional, desaprovado quando partitioned é true)

Atualizar função de validação.

O campo `options.partitioned`

Esse campo configura se o índice criado é particionado ou global.

Este campo inclui os valores a seguir:

Valores para o campo options.partitioned
Valor	Descrição	Notas
`true`	Crie o índice como particionado.	Pode ser usado apenas em um banco de dados particionado.
`false`	Crie o índice como global.	Pode ser usado em qualquer banco de dados.

O padrão segue a configuração partitioned para o banco de dados:

Configurações de partição
O banco de dados é particionado?	Valor `partitioned` padrão	Valores permitidos
True	`true`	`true`, `false`
Não	`false`	`false`

Copiando um documento de design

É possível copiar a versão mais recente de um documento de design em um novo documento especificando o documento de base e o documento de destino. A cópia é solicitada usando o método de solicitação COPY.

COPY é um comando não padrão do HTTP.

O exemplo a seguir solicita que o IBM Cloudant copie o documento de design allusers para o novo documento de design copyOfAllusers, e produza uma resposta que inclua o ID e a revisão do novo documento.

A cópia de um documento de design não reconstrói automaticamente os índices de visualização. Como outras visualizações, essas visualizações são recriadas na primeira vez que você acessa a nova visualização.

Veja o comando de exemplo a seguir para copiar um documento de design usando HTTP:

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

Veja o comando de exemplo a seguir para copiar um documento de design:

Atualmente, os SDKs do IBM Cloudant não oferecem suporte ao método COPY do HTTP.

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

Veja a resposta de exemplo a seguir para a solicitação de cópia:

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

A estrutura do comando de cópia

Método: COPY /$DATABASE/_design/$DDOC
Solicitação: Nenhum.
Resposta: JSON descrevendo o novo documento e revisão.
Funções permitidas: _design

Argumentos da consulta

Argumento

rev

Descrição: Revisão para copiar de.
Opcional: Sim.
Tipo: Sequência.

Cabeçalhos de HTTP

Cabeçalho

Destination

Descrição: Documento de destino (e revisão opcional)
Opcional: Nº

O documento de design de origem é especificado na linha de solicitação, enquanto o cabeçalho de HTTP Destination da solicitação especifica o documento de destino.

Copiando de uma revisão específica

Para copiar de uma versão específica, inclua o argumento rev na sequência de consultas.

O novo documento de design é criado usando a revisão especificada do documento de origem.

Veja o comando de exemplo a seguir para copiar uma revisão específica do documento de design usando HTTP:

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

Veja o comando de exemplo a seguir para copiar uma revisão específica do documento de design usando a linha de comandos:

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

Copiando em um documento de design existente

Para sobrescrever ou copiar em um documento existente, especifique a sequência de revisão atual para o documento de destino usando o parâmetro rev para a sequência do cabeçalho de HTTP Destination.

Veja o comando de exemplo a seguir para sobrescrever uma cópia existente do documento de design usando HTTP:

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

Veja o comando de exemplo a seguir para sobrescrever uma cópia existente do documento de design usando a linha de comandos:

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

O valor de retorno é o ID e a nova revisão do documento copiado.

Veja a resposta de exemplo a seguir para sobrescrever uma cópia existente do documento de design:

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

Excluindo um documento de design

É possível excluir um documento de design existente. A exclusão de um documento de design também exclui todos os índices de visualização associados e recupera o espaço correspondente em disco para os índices em questão.

Para excluir um documento de design com sucesso, deve-se especificar a revisão atual do documento de design usando o argumento de consulta rev.

Veja o comando de exemplo a seguir para excluir um documento de design usando HTTP:

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

Veja os exemplos a seguir para excluir um documento de design:

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

O exemplo do Go anterior requer o bloco de importação a seguir:

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

Veja a resposta de exemplo a seguir que inclui o ID do documento excluído e a revisão:

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

A estrutura do comando de exclusão

Método: DELETE /db/_design/$DDOC
Solicitação: Nenhum.
Resposta: JSON de documento de design excluído.
Funções permitidas: _design

Argumentos da consulta

Argumento

rev

Descrição: Revisão atual do documento para validação.
Opcional: Sim, se houver um cabeçalho If-Match .
Tipo: Sequência.

Cabeçalhos de HTTP

Cabeçalho

If-Match

Descrição: Revisão atual do documento para validação.
Opcional: Sim, se houver o argumento de consult rev.

Visualizações

Um uso importante de documentos de design é para a criação de visualizações. Para obter mais informações sobre a criação de visualizações, consulte Visualizações (MapReduce).

Índices

Todas as consultas operam em índices predefinidos que são definidos em documentos de design. Esses índices são definidos na lista a seguir:

Por exemplo, para criar um documento de design usado para procura, deve-se assegurar que duas condições sejam verdadeiras:

Você definiu o documento como um documento de design quando iniciou o _id com _design/.
Você criou um índice de pesquisa dentro do documento, no qual atualizou o documento com o campo apropriado ou criou um novo documento que inclui o índice de pesquisa.

Contanto que o documento de design do índice de procura exista e assim que o índice for construído, é possível fazer consultas usando-os.

Notas gerais sobre funções em documentos de design

As funções em documentos de design são executadas em diversos nós para cada documento e podem ser executadas várias vezes. Para evitar inconsistências, elas precisam ser idempotentes, ou seja, precisam se comportar da mesma forma quando executadas várias vezes ou em nós diferentes. Em particular, não se deve usar funções que gerem números aleatórios ou retornem o tempo atual.

Funções de filtro

Os documentos de design com options.partitioned configurado como true não podem conter um campo filters.

Funções de filtro são documentos de design que filtram o feed de mudanças. Elas funcionam aplicando testes em cada um dos objetos incluídos no feed de mudanças.

Se qualquer um dos testes de função falhar, o objeto será "removido" ou "filtrado" do feed. Se a função retornar um resultado true quando aplicada a uma mudança, a mudança permanecerá no feed. Em outras palavras, as funções de filtro "removem" ou "ignoram" as mudanças que você não deseja monitorar.

As funções de filtro também podem ser usadas para modificar uma tarefa de replicação.

As funções de filtro requerem dois argumentos: doc e req.

O argumento doc representa o documento que é testado para filtragem.

O argumento req inclui mais informações sobre a solicitação. Com esse argumento, é possível criar funções de filtro que são mais dinâmicas porque são baseadas em diversos fatores, como parâmetros de consulta ou contexto do usuário.

Por exemplo, seria possível controlar aspectos dos testes de função de filtro usando valores dinâmicos fornecidos como parte da solicitação de HTTP. No entanto, em muitos casos de uso de função de filtro, apenas o parâmetro doc é usado.

Veja o documento de design de exemplo a seguir que inclui uma função de filtro:

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

Consulte o exemplo a seguir de uma função 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!
}

Altera funções do filtro de alimentação

Para aplicar uma função de filtro no feed de mudanças, inclua o parâmetro filter na consulta _changes, fornecendo o nome do filtro a ser usado.

Veja o exemplo a seguir de uma função de filtro aplicada a uma consulta do tipo “ _changes ” (Avaliação de dados) por meio de HTTP:

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

Veja os exemplos a seguir de uma função de filtro aplicada a uma consulta _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))

O exemplo do Go anterior requer o bloco de importação a seguir:

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

Função do filtro `req` argumento

O argumento req fornece acesso a aspectos da solicitação de HTTP usando a propriedade query.

Veja o exemplo a seguir de fornecimento de um argumento req usando HTTP:

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

Veja o exemplo a seguir de fornecimento de um argumento req:

Atualmente, os SDKs do IBM Cloudant não oferecem suporte à opção “ status ” para a solicitação “ _changes ”.

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

Veja o filtro de exemplo a seguir usando um argumento req fornecido:

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!
}

Funções de filtro predefinidas

Há inúmeras funções de filtro predefinido disponíveis:

_design: Aceita apenas mudanças em documentos de design.
_doc_ids: Aceita apenas mudanças para documentos cujo ID é especificado no parâmetro doc_ids ou no documento JSON fornecido.
_selector: Aceita apenas alterações em documentos que correspondam a um seletor especificado, definido utilizando a mesma sintaxe de seletor descrita na seção “Solicitação”, que é usada para _find.
_view: Com esta função, é possível usar uma função de mapa existente como o filtro.

O filtro `_design`

O filtro _design aceita mudanças somente para documentos de design dentro do banco de dados solicitado.

O filtro não requer nenhum argumento.

As mudanças são listadas para todos os documentos de design dentro do banco de dados.

Veja o exemplo a seguir de aplicação do filtro _design usando HTTP:

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

Veja os aplicativos de exemplo a seguir do filtro _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))

O exemplo do Go anterior requer o bloco de importação a seguir:

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

Veja a resposta de exemplo a seguir (abreviada) depois da aplicação do 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"
    },
    ...
  ]
}

O filtro `_doc_ids`

O filtro _doc-ids aceita apenas mudanças para documentos com IDs especificados. Os IDs são especificados em um parâmetro doc_ids ou dentro de um documento JSON fornecido como parte da solicitação original.

Veja o exemplo a seguir de aplicação do filtro _doc_ids usando HTTP:

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

Veja os aplicativos de exemplo a seguir do filtro _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))

O exemplo do Go anterior requer o bloco de importação a seguir:

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

Veja o documento JSON de exemplo a seguir que lista IDs de documentos para correspondência durante a filtragem:

{
  "doc_ids": [
    "ExampleID"
  ]
}

Veja a resposta de exemplo a seguir (abreviada) depois da filtragem por _docs_ids:

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

O filtro `_selector`

O filtro _selector aceita apenas alterações para documentos que correspondam a um seletor especificado, o qual é definido usando a mesma sintaxe de seletor utilizada para _find.

Para obter mais exemplos que mostrem o uso desse filtro, consulte as informações sobre a sintaxe do seletor.

Veja o exemplo a seguir de aplicação do filtro _selector usando HTTP:

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

Veja os aplicativos de exemplo a seguir do filtro _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))

O exemplo do Go anterior requer o bloco de importação a seguir:

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

Veja o documento JSON de exemplo a seguir que inclui a expressão do seletor para usar durante a filtragem:

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

Veja a resposta de exemplo a seguir (abreviada) após a filtragem usando um seletor:

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

O filtro `_view`

Usando o filtro _view, é possível usar uma função map existente como o filtro.

A função map pode emitir saída como resultado do processamento de um documento específico. Quando esta situação ocorre, o filtro considera o documento permitido e o inclui na lista de documentos que você mudou.

Veja o exemplo a seguir de aplicação do filtro _view usando HTTP:

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

Veja os aplicativos de exemplo a seguir do filtro _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))

Veja a resposta de exemplo a seguir (abreviada) após a filtragem usando uma função map:

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

Validadores de atualização

Os documentos de design com options.partitioned configurado como true não podem conter um campo validate_doc_update.

Os validadores de atualização determinam se um documento deve ser gravado em disco quando são feitas tentativas de inserção e atualização. Eles não requerem uma consulta, pois são executados implicitamente durante esse processo. Se uma mudança for rejeitada, o validador de atualização responderá com um erro customizado.

Os validadores de atualização requerem quatro argumentos:

Argumentos para o validador de atualização
Argumento	Propósito
`newDoc`	A versão do documento transmitida na solicitação.
`oldDoc`	A versão do documento atualmente no banco de dados ou `null`, se nenhuma existir.
`secObj`	O objeto de segurança para o banco de dados.
`userCtx`	Contexto referente ao usuário autenticado atualmente, como `name` e `roles`.

Os validadores de atualização não se aplicam quando um documento de design é atualizado por um usuário administrativo. Essa prática assegura que os administradores nunca se bloqueiem acidentalmente.

Veja o documento de design de exemplo a seguir com um validador de atualização:

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

Veja o exemplo a seguir de um validador de atualização:

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

Veja a resposta de exemplo a seguir de um validador de atualização:

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

Recuperando informações sobre um documento de design

Dois terminais fornecem informações adicionais sobre documentos de design: _info e _search_info.

O terminal `_info`

O terminal _info retorna informações sobre um documento de design específico, incluindo o índice de visualização, o tamanho do índice de visualização e o status do documento de design, além de informações de índice de visualização associadas.

Método: GET /db/_design/$DDOC/_info
Solicitação: Nenhum
Resposta: JSON que contém as informações do documento de design.
Funções permitidas: _reader

Veja o exemplo a seguir de recuperação de informações sobre o documento de design recipesdd de dentro do banco de dados recipes usando HTTP:

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

Veja os exemplos a seguir de recuperação de informações sobre o documento de design recipesdd de dentro do banco de dados 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);
});

A resposta JSON inclui os campos individuais a seguir:

name

Nome ou ID do documento de design.

view_index

índice de visualização

compact_running: Indica se uma rotina de compactação é executada na visualização.
disk_size: Tamanho, em bytes, da visualização conforme armazenada no disco.
language: Linguagem que é usada para definição de visualizações.
purge_seq: A sequência de limpeza que foi processada.
signature: Assinatura MD5 das visualizações para o documento de design.
update_seq: A sequência de atualização do banco de dados correspondente que foi indexado.
updater_running: Indica se a visualização está sendo atualizada.
waiting_clients: Número de clientes que estão esperando em visualizações deste documento de design.
waiting_commit: Indica se o banco de dados subjacente tem confirmações pendentes que precisam ser processadas.

Consulte a resposta de exemplo a seguir no 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
	}
}

O terminal `_search_info`

O terminal _search_info retorna informações sobre uma procura especificada que é definida dentro de um documento de design específico.

Método: GET /db/_design/$DDOC/_search_info/yourSearch
Solicitação: Nenhum
Resposta: JSON que contém informações sobre a procura especificada.
Funções permitidas*: _reader

Veja o exemplo a seguir de obtenção de informações sobre a procura description, que é definida dentro do documento de design app armazenado no banco de dados foundbite, usando HTTP:

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

Veja os exemplos a seguir de obtenção de informações sobre o índice de pesquisa description, que é definido dentro do documento de design app que é armazenado no banco de dados 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))

A estrutura JSON inclui os campos individuais a seguir:

name: Nome ou ID da Procura dentro do documento de design.
search_index: O Índice de Procura
pending_seq: O número de sequência de mudanças no banco de dados que atingiu o índice Lucene, tanto na memória quanto no disco.
doc_del_count: Número de documentos excluídos no índice.
doc_count: Número de documentos no índice.
disk_size: O tamanho do índice em disco, em bytes.
committed_seq: O número de sequência de mudanças no banco de dados que foram confirmadas para o índice Lucene no disco.

Consulte a resposta de exemplo a seguir no formato JSON:

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

Como funcionam os documentos de design

Como funcionam os documentos de design

Criando ou atualizando um documento de design

O campo options.partitioned

Copiando um documento de design

A estrutura do comando de cópia

Copiando de uma revisão específica

Copiando em um documento de design existente

Excluindo um documento de design

A estrutura do comando de exclusão

Visualizações

Índices

Notas gerais sobre funções em documentos de design

Funções de filtro

Altera funções do filtro de alimentação

Função do filtro req argumento

Funções de filtro predefinidas

O filtro _design

O filtro _doc_ids

O filtro _selector

O filtro _view

Validadores de atualização

Recuperando informações sobre um documento de design

O terminal _info

O terminal _search_info

O campo `options.partitioned`

Função do filtro `req` argumento

O filtro `_design`

O filtro `_doc_ids`

O filtro `_selector`

O filtro `_view`

O terminal `_info`

O terminal `_search_info`