Usando visualizações

Use visualizações para procurar conteúdo dentro de um banco de dados que corresponda a critérios específicos. Os critérios são especificados dentro da definição de visualização.

Os critérios também podem ser fornecidos como argumentos quando você usa a visualização.

Consultando uma visualização

Para consultar uma visualização, envie uma solicitação GET com o formato a seguir:

Método
Emita uma consulta de partição usando o comando a seguir, GET $SERVICE_URL/$DATABASE/_partition/$PARTITION_KEY/_design/$DDOC/_view/$VIEW_NAME. Ou emita uma consulta global usando o comando a seguir, GET $SERVICE_URL/$DATABASE/_design/$DDOC/_view/$VIEW_NAME.
Solicitação
Nenhum
Resposta
JSON dos documentos que são retornados pela visualização.
Funções permitidas
_reader

A solicitação é executada:

  • O $VIEW_NAME especificado no documento de projeto $DDOC especificado na base de dados $DATABASE, cujos resultados estão restritos à área especificada $PARTITION_KEY Dados partição.
  • O $VIEW_NAME especificado no documento de projeto $DDOC especificado na base de dados “ $DATABASE ”.

Os exemplos neste documento variam entre consultas de partição e globais para propósitos ilustrativos. A menos que seja indicado de outra forma, a modificação do caminho para integrar ou remover o nome da partição funciona para qualquer tipo de consulta de visualização.

Argumentos de consulta e corpo JSON

As consultas globais podem usar todos os argumentos de consulta e corpo JSON. As consultas de partição podem usar apenas o subconjunto que é indicado na tabela.

Argumentos de subconjunto da consulta e do corpo JSON disponíveis para consultas particionadas
Argumento Descrição Opcional Tipo Padrão Valores suportados Consulta de partição
conflicts Especifique se deseja incluir uma lista de revisões conflitantes na propriedade _conflicts do documento retornado. Ignorado se include_docs não estiver definido como true. True Booleano Não True
descending Retorne os documentos em ordem descending by key. True Booleano Não True
end_key Pare de retornar registros quando a chave especificada for acessada. True Sequência ou matriz JSON True
end_key_docid Pare de retornar registros quando o ID do documento especificado for acessado. True Sequência True
group Especifique se os resultados reduzidos devem ser agrupados por chave. Válido somente se uma função de redução estiver definida na visualização. Se a exibição emitir chaves no formato de matriz JSON, será possível reduzir ainda mais os grupos com base no número de elementos da matriz com o parâmetro group_level. True Booleano Não True
group_level Especifique um nível de grupo a ser usado. Aplicável apenas se a visualização utilizar chaves que sejam matrizes JSON. Implica que o grupo é true. O nível de grupo agrupa os resultados reduzidos pelo número especificado de elementos da matriz. Se não for definido, os resultados serão agrupados por toda a chave do array, retornando um valor reduzido para cada chave completa. True Numéricos True
include_docs Inclua o conteúdo completo dos documentos na resposta. True Booleano Não True
inclusive_end Inclua linhas com o end_key especificado. True Booleano Sim True
key Retorne somente documentos que correspondam à chave especificada. As chaves são valores JSON e devem ser codificadas por URL. True Matriz JSON True
keys Especifique para retornar apenas documentos que correspondam a qualquer uma das chaves especificadas. Representação em cadeia de caracteres de uma matriz JSON de chaves que correspondem ao tipo de chave emitido pela função de exibição. True Sequência ou matriz JSON True
limit Limite o número de documentos retornados à contagem especificada. True Numéricos True
reduce Use a função reduce. True Booleano Sim True
skip Ignore esse número de linhas desde o início. True Numéricos 0 True
stable Especifique se deve ser usada a mesma réplica do índice em cada solicitação. O valor padrão false entra em contato com todas as réplicas e retorna o resultado do primeiro respondedor mais rápido. Definir esse parâmetro como true, quando usado em conjunto com update=false, pode melhorar a consistência, mas em detrimento de um aumento na latência e uma redução na taxa de transferência, caso a réplica selecionada não seja a mais rápida entre as réplicas disponíveis.

Observação: Em geral, não é aconselhável definir esse parâmetro como “ true ” e isso não é recomendado quando se utiliza “ update=true ”.

 True Booleano Não Não
stale

Nota: o stale foi descontinuado. Em vez disso, use stable e update.

Especifique se deseja usar os resultados de uma visualização desatualizada sem acionar uma reconstrução de todas as visualizações contidas no documento de projeto correspondente.

  • ok é equivalente a stable=true&update=false.
  • update_after é equivalente a stable=true&update=lazy.
 True Sequência Não Não
start_key Retorne os registros, começando com a chave especificada. True Sequência ou matriz JSON True
start_key_docid Retorne os registros, começando com o ID do documento especificado. True Sequência True
update

Especifique se a visualização em questão deve ou não ser atualizada antes de responder ao usuário

  • true- Retornar os resultados depois que a visualização for atualizada
  • false- Retornar os resultados sem atualizar a visualização
  • lazy- Retornar os resultados da visualização sem esperar por uma atualização, mas atualizá-los imediatamente após a solicitação.
 True Sequência Sim True

O uso de include_docs=true pode resultar em implicações de desempenho.

Veja o exemplo de uso de HTTP para recuperar uma lista dos primeiros 10 documentos, incluindo o conteúdo completo desses documentos, a partir de uma partição de um banco de dados, aplicando uma visualização criada pelo usuário.

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

Veja o exemplo de uso de HTTP para recuperar uma lista dos primeiros 10 documentos de um banco de dados aplicando uma visualização criada pelo usuário.

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

Veja o exemplo para recuperar uma lista dos primeiros 10 documentos, incluindo o conteúdo completo de cada um deles, da partição “ small-appliances ” de um banco de dados, aplicando a visualização “ byApplianceProdId ”, criada pelo usuário.

As bibliotecas de clientes utilizam o método POST em vez de GET , pois ambos apresentam o mesmo comportamento.

curl -X GET "$SERVICE_URL/products/_partition/small-appliances/_design/appliances/_view/byApplianceProdId?include_docs=true&limit=10"

import com.ibm.cloud.cloudant.v1.Cloudant;
import com.ibm.cloud.cloudant.v1.model.PostPartitionViewOptions;
import com.ibm.cloud.cloudant.v1.model.ViewResult;
Cloudant service = Cloudant.newInstance();
PostPartitionViewOptions viewOptions =
    new PostPartitionViewOptions.Builder()
        .db("products")
        .ddoc("appliances")
        .includeDocs(true)
        .limit(10)
        .partitionKey("small-appliances")
        .view("byApplianceProdId")
        .build();
ViewResult response =
    service.postPartitionView(viewOptions).execute()
        .getResult();
System.out.println(response);

const { CloudantV1 } = require('@ibm-cloud/cloudant');
const service = CloudantV1.newInstance({});
service.postPartitionView({
  db: 'products',
  ddoc: 'appliances',
  includeDocs: true,
  limit: 10,
  partitionKey: 'small-appliances',
  view: 'byApplianceProdId'
}).then(response => {
  console.log(response.result);
});

from ibmcloudant.cloudant_v1 import CloudantV1
service = CloudantV1.new_instance()
response = service.post_partition_view(
  db='products',
  ddoc='appliances',
  include_docs=True,
  limit=10,
  partition_key='small-appliances',
  view='byApplianceProdId'
).get_result()
print(response)

postPartitionViewOptions := service.NewPostPartitionViewOptions(
  "products",
  "small-appliances",
  "appliances",
  "byApplianceProdId",
)
postPartitionViewOptions.SetIncludeDocs(true)
postPartitionViewOptions.SetLimit(10)
viewResult, response, err := service.PostPartitionView(postPartitionViewOptions)
if err != nil {
  panic(err)
}
b, _ := json.MarshalIndent(viewResult, "", "  ")
fmt.Println(string(b))

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

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

Todos os exemplos do Go requerem que o objeto service seja inicializado. Para obter mais informações, consulte a seção Autenticação da documentação da API para exemplos.

Veja o exemplo para recuperar uma lista dos primeiros 10 documentos de um banco de dados aplicando a visualização getVerifiedEmails criada pelo usuário.

As bibliotecas de clientes utilizam o método POST em vez de GET , pois ambos apresentam o mesmo comportamento.

curl -X GET "$SERVICE_URL/users/_design/allusers/_view/getVerifiedEmails?limit=10"

import com.ibm.cloud.cloudant.v1.Cloudant;
import com.ibm.cloud.cloudant.v1.model.PostViewOptions;
import com.ibm.cloud.cloudant.v1.model.ViewResult;
Cloudant service = Cloudant.newInstance();
PostViewOptions viewOptions = new PostViewOptions.Builder()
    .db("users")
    .ddoc("allusers")
    .view("getVerifiedEmails")
    .limit(10)
    .build();
ViewResult response =
    service.postView(viewOptions).execute()
        .getResult();
System.out.println(response);

const { CloudantV1 } = require('@ibm-cloud/cloudant');
const service = CloudantV1.newInstance({});
service.postView({
  db: 'users',
  ddoc: 'allusers',
  view: 'getVerifiedEmails',
  limit: 10
}).then(response => {
  console.log(response.result);
});

from ibmcloudant.cloudant_v1 import CloudantV1
service = CloudantV1.new_instance()
response = service.post_view(
  db='users',
  ddoc='allusers',
  view='getVerifiedEmails',
  limit=10
).get_result()
print(response)

postViewOptions := service.NewPostViewOptions(
  "users",
  "allusers",
  "getVerifiedEmails",
)
postViewOptions.SetLimit(10)
viewResult, response, err := service.PostView(postViewOptions)
if err != nil {
  panic(err)
}
b, _ := json.MarshalIndent(viewResult, "", "  ")
fmt.Println(string(b))

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

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

Todos os exemplos do Go requerem que o objeto service seja inicializado. Para obter mais informações, consulte a seção Autenticação da documentação da API para exemplos.

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

{
  "offset": 0,
  "rows": [
    {
      "id": "abc125",
      "key": "amelie.smith@aol.com",
      "value": [
        "Amelie Smith",
        true,
        "2020-04-24T10:42:59.000Z"
      ]
    },
    {
      "id": "abc123",
      "key": "bob.smith@aol.com",
      "value": [
        "Bob Smith",
        true,
        "2019-01-24T10:42:59.000Z"
      ]
    }
  ],
  "total_rows": 2
}

Índices

Quando uma visualização é definida em um documento de design, um índice correspondente também é criado com base nas informações definidas dentro da visualização. Use índices para localizar documentos por critérios diferentes de seu campo _id. Por exemplo, é possível selecionar por um campo ou por uma combinação de campos. Também é possível selecionar por um valor calculado usando o conteúdo do documento. O índice é preenchido assim que o documento de design é criado. Em bancos de dados grandes, esse processo pode demorar um pouco.

Se um dos eventos a seguir ocorrer, o conteúdo do índice será atualizado de forma incremental e automática:

  • Um novo documento é incluído no banco de dados.
  • Um documento existente é excluído do banco de dados.
  • Um documento existente no banco de dados é atualizado.

Os índices de visualização são completamente reconstruídos quando a definição de visualização muda ou quando outra definição de visualização no mesmo documento de design muda. A reconstrução garante que as mudanças nas definições de visualização sejam refletidas nos índices de visualização. Para assegurar que a reconstrução aconteça, uma 'impressão digital' da definição de visualização é criada sempre que o documento de design é atualizado. Se a impressão digital mudar, os índices de visualização serão reconstruídos.

As reconstruções de índice de visualização ocorrem quando você muda qualquer visualização entre todas as visualizações definidas no documento de design. Por exemplo, se você tiver um documento de design com três visualizações e atualizar o documento de design, todos os três índices de visualização dentro do documento de design serão reconstruídos. Para mudar um documento de design para um banco de dados maior, consulte o Guia de gerenciamento de documento de design.

Se o banco de dados tiver sido atualizado recentemente, os resultados poderão estar atrasados quando a visualização for acessada. O atraso é afetado pelo número de mudanças no banco de dados e quando o índice de visualização não é atual porque o conteúdo do banco de dados foi modificado.

Não é possível eliminar esses atrasos. Para bancos de dados recém-criados, é possível reduzir os atrasos criando a definição de visualização no documento de design em seu banco de dados antes de inserir ou atualizar documentos. A criação da definição de visualização no documento de design causa atualizações incrementais no índice quando os documentos são inseridos.

Se a velocidade de resposta é mais importante do que ter dados atualizados, uma alternativa é permitir que os usuários acessem uma versão antiga do índice de visualização. Para permitir o acesso a uma versão antiga do índice de visualização, use o parâmetro de sequência de consultas update ao fazer uma consulta de visualização.

Para salvar versões mais antigas do índice sem usar o processador de indexação, faça os índices interromperem a construção configurando "autoupdate": {"indexes": false}. Ou é possível parar a atualização automática feita pelas visualizações incluindo uma das opções a seguir em um documento de design. Será possível fazer todos os tipos de índice interromperem a indexação se você configurar "autoupdate": false.

Consulte os seguintes exemplos:

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

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

Visualizar criação recente

Por padrão, todos os resultados do índice refletem o estado atual do banco de dados. O IBM Cloudant constrói seus índices automaticamente e de forma assíncrona em segundo plano. Essa prática geralmente significa que o índice está totalmente atualizado quando você o consulta. Se não, por padrão, IBM Cloudant aplica as atualizações restantes no momento da consulta.

IBM Cloudant fornece alguns parâmetros, descritos a seguir, para alterar esse comportamento. Não recomendamos o uso pois os efeitos colaterais normalmente superam seus benefícios.

Parâmetros

A opção update indica se você está preparado para aceitar resultados de visualização sem esperar que a visualização seja atualizada. O valor padrão é true, o que significa que a visualização é atualizada antes de os resultados serem retornados. O valor lazy significa que os resultados são retornados antes de a visualização ser atualizada, mas que a visualização deve ser atualizada de qualquer maneira.

Embora o IBM Cloudant se esforce para manter os índices atualizados em segundo plano, não há garantia quanto ao grau de desatualização da visualização quando consultada com update=false ou update=lazy.

A opção stable indica se você preferiria obter resultados por meio de um único conjunto consistente de shards. O valor “ false ” significa que todas as réplicas de fragmento disponíveis são consultadas e IBM Cloudant usa a resposta mais rápida resposta. Por outro lado, a configuração stable=true força o banco de dados a usar apenas uma réplica do índice índice.

O uso do stable=true pode causar alta latência, pois ele consulta apenas uma das cópias do índice, mesmo que as outras cópias respondam mais rapidamente.

Combinando parâmetros

Se você especificar stable=false e update=false, verá uma maior inconsistência entre os resultados, mesmo para a mesma consulta e sem fazer alterações no banco de dados. Não recomendamos essa combinação, a menos que você tenha certeza de que seu sistema pode tolerar esse comportamento.

Classificando linhas retornadas

Os dados que são retornados por uma consulta de visualização estão na forma de uma matriz. Cada elemento da matriz é classificado por meio de UTF-8. A classificação é aplicada à chave definida na função de visualização.

A ordem básica da saída é mostrada na tabela a seguir:

Ordem das linhas retornadas
Valor Pedido
null Primeiro
false
true
Números
Texto (minúsculo)
Texto (maiúsculo)
Matrizes (de acordo com os valores de cada elemento, usando a ordem fornecida nesta tabela)
Objetos (de acordo com os valores das chaves em ordem de chave usando a ordem fornecida nesta tabela) Último

É possível reverter a ordem das informações de visualização retornadas configurando o valor de consulta descending como true.

Quando você emite uma solicitação de visualização que especifica o parâmetro keys, os resultados são retornados na mesma ordem que a matriz keys fornecida.

Veja o exemplo de uso de HTTP para solicitar os registros em ordem de classificação reversa:

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

Veja o exemplo de solicitação dos registros em ordem de classificação reversa.

As bibliotecas do cliente usam o método POST em vez do GET porque eles têm um comportamento semelhante.

curl -X GET "$SERVICE_URL/users/_design/allusers/_view/getVerifiedEmails?descending=true"

import com.ibm.cloud.cloudant.v1.Cloudant;
import com.ibm.cloud.cloudant.v1.model.PostViewOptions;
import com.ibm.cloud.cloudant.v1.model.ViewResult;
Cloudant service = Cloudant.newInstance();
PostViewOptions viewOptions = new PostViewOptions.Builder()
    .db("users")
    .ddoc("allusers")
    .view("getVerifiedEmails")
    .descending(true)
    .build();
ViewResult response =
    service.postView(viewOptions).execute()
        .getResult();
System.out.println(response);

const { CloudantV1 } = require('@ibm-cloud/cloudant');
const service = CloudantV1.newInstance({});
service.postView({
  db: 'users',
  ddoc: 'allusers',
  view: 'getVerifiedEmails',
  descending: true
}).then(response => {
  console.log(response.result);
});

from ibmcloudant.cloudant_v1 import CloudantV1
service = CloudantV1.new_instance()
response = service.post_view(
  db='users',
  ddoc='allusers',
  view='getVerifiedEmails',
  descending=True
).get_result()
print(response)

postViewOptions := service.NewPostViewOptions(
  "users",
  "allusers",
  "getVerifiedEmails",
)
postViewOptions.SetDescending(true)
viewResult, response, err := service.PostView(postViewOptions)
if err != nil {
  panic(err)
}
b, _ := json.MarshalIndent(viewResult, "", "  ")
fmt.Println(string(b))

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

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

Todos os exemplos do Go requerem que o objeto service seja inicializado. Para obter mais informações, consulte a seção Autenticação da documentação da API para exemplos.

Veja a resposta de exemplo da solicitação dos registros em ordem de classificação reversa:

{
  "total_rows": 2,
  "offset": 0,
  "rows": [
    {
      "id": "abc123",
      "key": "bob.smith@aol.com",
      "value": [
        "Bob Smith",
        true,
        "2019-01-24T10:42:59.000Z"
      ]
    },
    {
      "id": "abc125",
      "key": "amelie.smith@aol.com",
      "value": [
        "Amelie Smith",
        true,
        "2020-04-24T10:42:59.000Z"
      ]
    }
  ]
}

Especificando chaves de início e de término

Os argumentos de consulta start_key e end_key podem ser usados para especificar o intervalo de valores que são retornados ao consultar a visualização.

A direção de classificação é sempre aplicada primeiro. Em seguida, a filtragem é aplicada usando os argumentos de consulta start_key e end_key. É possível que nenhuma linha corresponda ao seu intervalo de chaves se os planos de classificação e filtragem não fizerem sentido quando combinados.

Veja o exemplo de uso de HTTP para fazer uma consulta global que inclui os argumentos de consulta start_key e end_key:

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

Veja o exemplo de uma consulta global que inclui os argumentos de consulta start_key e end_key.

As bibliotecas de clientes utilizam o método POST em vez de GET , pois ambos apresentam o mesmo comportamento.

curl -X GET "$SERVICE_URL/users/_design/allusers/_view/getVerifiedEmails?start_key=\"alpha\"&end_key=\"beta\""

import com.ibm.cloud.cloudant.v1.Cloudant;
import com.ibm.cloud.cloudant.v1.model.PostViewOptions;
import com.ibm.cloud.cloudant.v1.model.ViewResult;
Cloudant service = Cloudant.newInstance();
PostViewOptions viewOptions = new PostViewOptions.Builder()
    .db("users")
    .ddoc("allusers")
    .view("getVerifiedEmails")
    .startKey("alpha")
    .endKey("beta")
    .build();
ViewResult response =
    service.postView(viewOptions).execute()
        .getResult();
System.out.println(response);

const { CloudantV1 } = require('@ibm-cloud/cloudant');
const service = CloudantV1.newInstance({});
service.postView({
  db: 'users',
  ddoc: 'allusers',
  view: 'getVerifiedEmails',
  startKey: 'alpha',
  endKey: 'beta'
}).then(response => {
  console.log(response.result);
});

from ibmcloudant.cloudant_v1 import CloudantV1
service = CloudantV1.new_instance()
response = service.post_view(
  db='users',
  ddoc='allusers',
  view='getVerifiedEmails',
  start_key='alpha',
  end_key='beta'  
).get_result()
print(response)

postViewOptions := service.NewPostViewOptions(
  "users",
  "allusers",
  "getVerifiedEmails",
)
postViewOptions.StartKey = "alpha"
postViewOptions.EndKey = "beta"
viewResult, response, err := service.PostView(postViewOptions)
if err != nil {
  panic(err)
}
b, _ := json.MarshalIndent(viewResult, "", "  ")
fmt.Println(string(b))

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

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

Todos os exemplos do Go requerem que o objeto service seja inicializado. Para obter mais informações, consulte a seção Autenticação da documentação da API para exemplos.

Por exemplo, se você tiver um banco de dados que retorna um resultado ao usar uma consulta do tipo “ start_key ” com alpha e um end_key de beta, você obteria um erro 400 (solicitação inválida) com uma ordem reversa. A razão é que as entradas na visualização são revertidas antes que o filtro de chave seja aplicado.

Veja o exemplo que usa HTTP para ilustrar porque reverter a ordem de start_key e end_key pode gerar um erro de análise da consulta:

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

Veja o exemplo ilustrando porque reverter a ordem de start_key e end_key pode causar um erro 400.

As bibliotecas de clientes utilizam o método POST em vez de GET , pois ambos apresentam o mesmo comportamento.

curl -X GET "$SERVICE_URL/users/_design/allusers/_view/getVerifiedEmails?descending=true&start_key=\"alpha\"&end_key=\"beta\""

import com.ibm.cloud.cloudant.v1.Cloudant;
import com.ibm.cloud.cloudant.v1.model.PostViewOptions;
import com.ibm.cloud.cloudant.v1.model.ViewResult;
Cloudant service = Cloudant.newInstance();
PostViewOptions viewOptions = new PostViewOptions.Builder()
    .db("users")
    .ddoc("allusers")
    .view("getVerifiedEmails")
    .descending(true)
    .startKey("alpha")
    .endKey("beta")
    .build();
ViewResult response =
    service.postView(viewOptions).execute()
        .getResult();
System.out.println(response);

const { CloudantV1 } = require('@ibm-cloud/cloudant');
const service = CloudantV1.newInstance({});
service.postView({
  db: 'users',
  ddoc: 'allusers',
  view: 'getVerifiedEmails',
  descending: true,
  startKey: 'alpha',
  endKey: 'beta'
}).then(response => {
  console.log(response.result);
});

from ibmcloudant.cloudant_v1 import CloudantV1
service = CloudantV1.new_instance()
response = service.post_view(
  db='users',
  ddoc='allusers',
  view='getVerifiedEmails',
  descending=True,  
  start_key='alpha',
  end_key='beta'  
).get_result()
print(response)

postViewOptions := service.NewPostViewOptions(
  "users",
  "allusers",
  "getVerifiedEmails",
)
postViewOptions.SetDescending(true)
postViewOptions.StartKey = "alpha"
postViewOptions.EndKey = "beta"
viewResult, response, err := service.PostView(postViewOptions)
if err != nil {
  panic(err)
}
b, _ := json.MarshalIndent(viewResult, "", "  ")
fmt.Println(string(b))

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

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

Todos os exemplos do Go requerem que o objeto service seja inicializado. Para obter mais informações, consulte a seção Autenticação da documentação da API para exemplos.

O end_key de beta é visto antes do start_key de alpha, resultando em um erro de análise de consulta.

A solução é reverter não apenas a ordem de classificação, mas também os valores de parâmetro start_key e end_key.

O exemplo a seguir mostra a filtragem correta e a reversão da ordem de saída, usando o argumento de consulta descending e revertendo os argumentos de consulta start_key e end_key.

Veja o exemplo que usa HTTP para aplicar a filtragem e a classificação corretas em uma consulta global:

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

Veja o exemplo para aplicar a filtragem e a classificação corretas a uma consulta global.

As bibliotecas de clientes utilizam o método POST em vez de GET , pois ambos apresentam o mesmo comportamento.

curl -X GET "$SERVER_URL/users/_design/allusers/_view/getVerifiedEmails?descending=true&start_key=\"beta\"&end_key=\"alpha\""

import com.ibm.cloud.cloudant.v1.Cloudant;
import com.ibm.cloud.cloudant.v1.model.PostViewOptions;
import com.ibm.cloud.cloudant.v1.model.ViewResult;
Cloudant service = Cloudant.newInstance();
PostViewOptions viewOptions = new PostViewOptions.Builder()
    .db("users")
    .ddoc("allusers")
    .view("getVerifiedEmails")
    .descending(true)
    .startKey("beta")
    .endKey("alpha")
    .build();
ViewResult response =
    service.postView(viewOptions).execute()
        .getResult();
System.out.println(response);

const { CloudantV1 } = require('@ibm-cloud/cloudant');
const service = CloudantV1.newInstance({});
service.postView({
  db: 'users',
  ddoc: 'allusers',
  view: 'getVerifiedEmails',
  descending: true,
  startKey: 'beta',
  endKey: 'alpha'
}).then(response => {
  console.log(response.result);
});

from ibmcloudant.cloudant_v1 import CloudantV1
service = CloudantV1.new_instance()
response = service.post_view(
  db='users',
  ddoc='allusers',
  view='getVerifiedEmails',
  descending=True,  
  start_key='beta',
  end_key='alpha'  
).get_result()
print(response)

postViewOptions := service.NewPostViewOptions(
  "users",
  "allusers",
  "getVerifiedEmails",
)
postViewOptions.SetDescending(true)
postViewOptions.StartKey = "beta"
postViewOptions.EndKey = "alpha"
viewResult, response, err := service.PostView(postViewOptions)
if err != nil {
  panic(err)
}
b, _ := json.MarshalIndent(viewResult, "", "  ")
fmt.Println(string(b))

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

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

Todos os exemplos do Go requerem que o objeto service seja inicializado. Para obter mais informações, consulte a seção Autenticação da documentação da API para exemplos.

Consultando uma visualização usando uma lista de chaves

Também é possível executar uma consulta fornecendo uma lista de chaves para uso.

Essa forma de solicitação de informações de um banco de dados usa o $VIEW_NAME especificado por meio do documento de design $DDOC especificado. Assim como o parâmetro keys para o método GET, é possível usar o método POST para especificar as chaves a serem usadas para recuperar os resultados da visualização. Em todos os outros aspectos, o método POST é o mesmo que a solicitação de API GET. Em particular, é possível usar qualquer um de seus parâmetros de consulta na sequência de consultas ou no corpo JSON.

Veja a solicitação de HTTP de exemplo que retorna todos os usuários,em que a chave para a visualização corresponde a amelie.smith@aol.com ou bob.smith@aol.com:

POST $SERVICE_URL/$DATABASE/_design/$DDOC/_view/$VIEW_NAME HTTP/1.1
Content-Type: application/json
{
  "keys": [
    "amelie.smith@aol.com",
    "bob.smith@aol.com"
  ]
}

Veja o exemplo de uma consulta global que retorna todos os usuários (em que a chave da visualização corresponde a amelie.smith@aol.com ou bob.smith@aol.com):

curl -X POST "$SERVICE_URL/users/_design/allusers/_view/getVerifiedEmails" -H "Content-Type: application/json" --data '{
  "keys": [
    "amelie.smith@aol.com",
    "bob.smith@aol.com"
  ]
}'

import com.ibm.cloud.cloudant.v1.Cloudant;
import com.ibm.cloud.cloudant.v1.model.PostViewOptions;
import com.ibm.cloud.cloudant.v1.model.ViewResult;
import java.util.Arrays;
Cloudant service = Cloudant.newInstance();
PostViewOptions viewOptions = new PostViewOptions.Builder()
    .db("users")
    .ddoc("allusers")
    .view("getVerifiedEmails")
    .keys(Arrays.asList("amelie.smith@aol.com", "bob.smith@aol.com"))
    .build();
ViewResult response =
    service.postView(viewOptions).execute()
        .getResult();
System.out.println(response);

const { CloudantV1 } = require('@ibm-cloud/cloudant');
const service = CloudantV1.newInstance({});
service.postView({
  db: 'users',
  ddoc: 'allusers',
  view: 'getVerifiedEmails',
  keys: ['amelie.smith@aol.com', 'bob.smith@aol.com']
}).then(response => {
  console.log(response.result);
});

from ibmcloudant.cloudant_v1 import CloudantV1
service = CloudantV1.new_instance()
response = service.post_view(
  db='users',
  ddoc='allusers',
  view='getVerifiedEmails',
  keys=['amelie.smith@aol.com', 'bob.smith@aol.com']
).get_result()
print(response)

postViewOptions := service.NewPostViewOptions(
  "users",
  "allusers",
  "getVerifiedEmails",
)
keys := []interface{}{"amelie.smith@aol.com", "bob.smith@aol.com"}
postViewOptions.SetKeys(keys)
viewResult, response, err := service.PostView(postViewOptions)
if err != nil {
  panic(err)
}
b, _ := json.MarshalIndent(viewResult, "", "  ")
fmt.Println(string(b))

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

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

Todos os exemplos do Go requerem que o objeto service seja inicializado. Para obter mais informações, consulte a seção Autenticação da documentação da API para exemplos.

A resposta contém as informações de visualização padrão, mas apenas para os documentos nos quais as chaves correspondem.

Veja a resposta de exemplo após a execução de uma consulta usando uma lista de chaves:

{
  "total_rows": 2,
  "offset": 0,
  "rows": [
    {
      "id": "abc125",
      "key": "amelie.smith@aol.com",
      "value": [
        "Amelie Smith",
        true,
        "2020-04-24T10:42:59.000Z"
      ]
    },
    {
      "id": "abc123",
      "key": "bob.smith@aol.com",
      "value": [
        "Bob Smith",
        true,
        "2019-01-24T10:42:59.000Z"
      ]
    }
  ]
}

Paginação

Use a paginação baseada em chave para exibições. Para obter detalhes e exemplos específicos, consulte o tópico da documentação da API Paging on view queries.

Busca de diversos documentos

A seção a seguir aborda uma solicitação do tipo “ POST ” para vários documentos de um banco de dados.

Para um aplicativo cliente, essa técnica é mais eficiente do que usar várias solicitações de API GET.

No entanto, include_docs=true pode requerer tempo de processamento adicional em comparação com o acesso apenas da visualização.

A razão é que quando se usa include_docs=true em uma consulta de visualização, todos os documentos resultantes devem ser recuperados para construir a resposta para o aplicativo cliente. Efetivamente, a série inteira de solicitações GET de documentos é executada, cada uma competindo por recursos com outras solicitações de aplicativos.

Uma maneira de minimizar esse efeito é recuperando resultados diretamente do arquivo de índice de visualização. Omita include_docs=true para recuperar resultados diretamente do arquivo de índice de visualização. Em vez disso, na função map em um documento de design, emita os campos necessários como o valor para o índice de visualização.

Por exemplo, em sua função map, é possível usar a especificação de design a seguir:

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

Veja a solicitação de exemplo que usa HTTP para obter o conteúdo completo de documentos que correspondem às chaves listadas dentro de uma partição:

POST $SERVICE_URL/$DATABASE/_partition/$PARTITION_KEY/_design/$DDOC/_view/$VIEW_NAME HTTP/1.1
Content-Type: application/json
{
  "include_docs": true,
  "keys" : [
    "1000043",
    "1000044"
  ]
}

Veja a solicitação de exemplo para obter o conteúdo completo de documentos que correspondem às chaves listadas dentro da partição products:

curl -X POST "$SERVICE_URL/products/_partition/small-appliances/_design/appliances/_view
/byApplianceProdId" -H "Content-Type: application/json" --data '{
  "include_docs": true,
  "keys" : [
    "1000043",
    "1000044"
  ]
}'

import com.ibm.cloud.cloudant.v1.Cloudant;
import com.ibm.cloud.cloudant.v1.model.PostPartitionViewOptions;
import com.ibm.cloud.cloudant.v1.model.ViewResult;
import java.util.Arrays;
Cloudant service = Cloudant.newInstance();
PostPartitionViewOptions viewOptions =
    new PostPartitionViewOptions.Builder()
        .db("products")
        .ddoc("appliances")
        .keys(Arrays.asList("1000043", "1000044"))
        .includeDocs(true)
        .partitionKey("small-appliances")
        .view("byApplianceProdId")
        .build();
ViewResult response =
    service.postPartitionView(viewOptions).execute()
        .getResult();
System.out.println(response);

const { CloudantV1 } = require('@ibm-cloud/cloudant');
const service = CloudantV1.newInstance({});
service.postPartitionView({
  db: 'products',
  ddoc: 'appliances',
  keys: ['1000043', '1000044'],
  includeDocs: true,
  partitionKey: 'small-appliances',
  view: 'byApplianceProdId'
}).then(response => {
  console.log(response.result);
});

from ibmcloudant.cloudant_v1 import CloudantV1
service = CloudantV1.new_instance()
response = service.post_partition_view(
  db='products',
  ddoc='appliances',
  keys=['1000043', '1000044'],
  include_docs=True,  
  partition_key='small-appliances',
  view='byApplianceProdId'
).get_result()
print(response)

postPartitionViewOptions := service.NewPostPartitionViewOptions(
  "products",
  "small-appliances",
  "appliances",
  "byApplianceProdId",
)
keys := []interface{}{"1000043", "1000044"}
postPartitionViewOptions.SetKeys(keys)
postPartitionViewOptions.SetIncludeDocs(true)
viewResult, response, err := service.PostPartitionView(postPartitionViewOptions)
if err != nil {
  panic(err)
}
b, _ := json.MarshalIndent(viewResult, "", "  ")
fmt.Println(string(b))

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

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

Todos os exemplos do Go requerem que o objeto service seja inicializado. Para obter mais informações, consulte a seção Autenticação da documentação da API para exemplos.

Veja a resposta de exemplo (abreviada), retornando o documento completo para cada dispositivo que corresponde a uma chave fornecida:

{
  "total_rows": 4,
  "offset": 1,
  "rows": [
    {
      "id": "small-appliances:1000043",
      "key": "1000043",
      "value": [
        "Bar",
        "Pro",
        "A professional, high powered innovative tool with a sleek design and outstanding performance"
      ],
      "doc": {
        "_id": "small-appliances:1000043",
        "_rev": "2-b595c929aabc3ab13415cd0cc03e665d",
        "type": "product",
        "taxonomy": [
          "Home",
          "Kitchen",
          "Small Appliances"
        ],
        "keywords": [
          "Bar",
          "Blender",
          "Kitchen"
        ],
        "productId": "1000043",
        "brand": "Bar",
        "name": "Pro",
        "description": "A professional, high powered innovative tool with a sleek design and outstanding performance",
        "colours": [
          "black"
        ],
        "price": 99.99,
        "image": "assets/img/barpro.jpg"
      }
    },
    {
      "id": "small-appliances:1000044",
      "key": "1000044",
      "value": [
        "Baz",
        "Omelet Maker",
        "Easily make delicious and fluffy omelets without flipping - Innovative design - Cooking and cleaning is easy"
      ],
      "doc": {
        "_id": "small-appliances:1000044",
        "_rev": "2-d54d022a9407ab9f06b1889cb2ab8a6e",
        "type": "product",
        "taxonomy": [
          "Home",
          "Kitchen",
          "Small Appliances"
        ],
        "keywords": [
          "Baz",
          "Maker",
          "Kitchen"
        ],
        "productId": "1000044",
        "brand": "Baz",
        "name": "Omelet Maker",
        "description": "Easily make delicious and fluffy omelets without flipping - Innovative design - Cooking and cleaning is easy",
        "colours": [
          "black"
        ],
        "price": 29.99,
        "image": "assets/img/bazomeletmaker.jpg"
      }
    }
  ]
}