IBM Cloud Docs
Utilizzo delle viste

Utilizzo delle viste

Utilizzate le viste per cercare all'interno di un database i contenuti che corrispondono a criteri specifici. I criteri sono specificati nella definizione della vista.

I criteri possono anche essere forniti come argomenti quando si utilizza la vista.

Interrogazione di una vista

Per interrogare una vista, inviare una richiesta GET con il seguente formato:

Metodo
Eseguire una query di partizione utilizzando il seguente comando, GET $SERVICE_URL/$DATABASE/_partition/$PARTITION_KEY/_design/$DDOC/_view/$VIEW_NAME. In alternativa, è possibile eseguire una query globale utilizzando il seguente comando, GET $SERVICE_URL/$DATABASE/_design/$DDOC/_view/$VIEW_NAME.
Richiesta
Nessuno
Risposta
JSON dei documenti restituiti dalla vista.
Ruoli consentiti
_reader

La richiesta viene eseguita o:

  • The specified $VIEW_NAME from the specified $DDOC design document within the $DATABASE database, which is constrained to results within the specified $PARTITION_KEY data partition.
  • The specified $VIEW_NAME from the specified $DDOC design document within the $DATABASE database.

Gli esempi riportati in questo documento variano tra query di partizione e query globali a scopo scopo illustrativo. A meno che non sia indicato diversamente, la modifica del percorso per incorporare o rimuovere il nome della partizione funziona per qualsiasi tipo di query di visualizzazione.

Argomenti della query e del corpo JSON

Le query globali possono utilizzare tutti gli argomenti della query e del corpo JSON. Le query di partizione possono utilizzare solo il sottoinsieme indicato nella tabella.

Sottoinsieme di argomenti della query e del corpo JSON disponibili per le query partizionate
Argomento Descrizione Facoltativo Immettere Valore predefinito Valori supportati Domanda di partizione
conflicts Specificare se includere un elenco di revisioni in conflitto nella proprietà _conflicts del documento restituito. Ignorato se include_docs non è impostato su true. Sì Booleano False Sì
descending Restituire i documenti in descending by key ordine. Sì Booleano False Sì
end_key Smette di restituire i record quando viene raggiunta la chiave specificata. Sì Stringa o array JSON Sì
end_key_docid Interrompe la restituzione dei record quando viene raggiunto l'ID documento specificato. Sì Stringa Sì
group Specificare se raggruppare i risultati ridotti per chiave. Valido solo se nella vista è definita una funzione di riduzione. Se la vista emette chiavi in formato array JSON, è possibile ridurre ulteriormente i gruppi in base al numero di elementi dell'array con il parametro group_level. Sì Booleano False Sì
group_level Specificare il livello di gruppo da utilizzare. Si applica solo se la vista utilizza chiavi che sono array JSON. Implica che il gruppo è true. Il livello di gruppo raggruppa i risultati ridotti per il numero specificato di elementi della matrice. Se non è impostato, i risultati vengono raggruppati in base alla chiave dell'intero array, restituendo un valore ridotto per ogni chiave completa. Sì Numerico Sì
include_docs Includere il contenuto completo dei documenti nella risposta. Sì Booleano False Sì
inclusive_end Include le righe con il valore end_key specificato. Sì Booleano Vero Sì
key Restituisce solo i documenti che corrispondono alla chiave specificata. Le chiavi sono valori JSON e devono essere codificate come URL. Sì Array JSON Sì
keys Specificare per restituire solo i documenti che corrispondono a una qualsiasi delle chiavi specificate. Rappresentazione stringa di un array JSON di chiavi che corrispondono al tipo di chiave emesso dalla funzione di visualizzazione. Sì Stringa o array JSON Sì
limit Limita il numero di documenti restituiti al conteggio specificato. Sì Numerico Sì
reduce Utilizzare la funzione reduce. Sì Booleano Vero Sì
skip Saltare questo numero di righe dall'inizio. Sì Numerico 0 Sì
stable Specificare se utilizzare la stessa replica dell'indice per ogni richiesta. Il valore predefinito false contatta tutte le repliche e restituisce il risultato del primo risponditore più veloce. Impostarlo su true, se usato con update=false, potrebbe migliorare la coerenza a scapito di un aumento della latenza e di una riduzione del throughput se la replica selezionata non è la più veloce tra quelle disponibili

Nota: In generale, l'impostazione di questo parametro su true è sconsigliata e non è raccomandata quando si usa update=true.

 Sì Booleano False No
stale

Nota: stale è deprecato. Usate invece stable e update

Specificare se utilizzare i risultati di una vista stantia senza attivare una ricostruzione di tutte le viste all'interno del progetto che la comprende

  • ok è equivalente a stable=true&update=false
  • update_after è equivalente a stable=true&update=lazy.
 Sì Stringa False No
start_key Restituisce i record a partire dalla chiave specificata. Sì Stringa o array JSON Sì
start_key_docid Restituisce i record a partire dall'ID documento specificato. Sì Stringa Sì
update

Specificare se la vista in questione deve essere aggiornata o meno prima di rispondere all'utente

  • true- Restituire i risultati dopo l'aggiornamento della vista
  • false- Restituire i risultati senza aggiornare la vista
  • lazy- Restituire i risultati della vista senza attendere l'aggiornamento, ma aggiornandoli immediatamente dopo la richiesta.
 Sì Stringa Vero Sì

L'uso di include_docs=true potrebbe avere implicazioni sulle prestazioni.

Si veda l'esempio di utilizzo di HTTP per recuperare un elenco dei primi 10 documenti che include il contenuto completo dei documenti da una partizione di un database, applicando una vista creata dall'utente.

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

Vedere l'esempio di utilizzo di HTTP per recuperare un elenco dei primi 10 documenti da un database, applicando una vista creata dall'utente.

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

Si veda l'esempio per recuperare un elenco dei primi 10 documenti che include il loro contenuto completo dalla small-appliances partizione di un database, applicando la vista byApplianceProdId creata dall'utente.

Le librerie client utilizzano il metodo POST invece di GET perché hanno lo stesso 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))

Il precedente esempio di Go richiede il seguente blocco di importazione:

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

Tutti gli esempi Go richiedono l'iniziazione dell'oggetto service. Per ulteriori informazioni, consultare la sezione Autenticazione della documentazione API per gli esempi.

Vedere l'esempio per recuperare un elenco dei primi 10 documenti da un database, applicando la vista getVerifiedEmails creata dall'utente.

Le librerie client utilizzano il metodo POST invece di GET perché hanno lo stesso 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))

Il precedente esempio di Go richiede il seguente blocco di importazione:

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

Tutti gli esempi Go richiedono l'iniziazione dell'oggetto service. Per ulteriori informazioni, consultare la sezione Autenticazione della documentazione API per gli esempi.

Vedere il seguente esempio di risposta alla richiesta:

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

Indici

Quando si definisce una vista in un documento di progettazione, viene creato anche un indice corrispondente, basato sulle informazioni definite all'interno della vista. Utilizzare gli indici per trovare i documenti in base a criteri diversi dal loro campo _id Ad esempio, si può selezionare in base a un campo, o una combinazione di campi, o da un valore calcolato in base al contenuto del documento. L'indice viene popolato non appena viene creato il documento di progettazione. Su database di grandi dimensioni, questo processo potrebbe richiedere un po' di tempo.

Se si verifica uno dei seguenti eventi, il contenuto dell'indice viene aggiornato in modo incrementale e automatico:

  • Un nuovo documento viene aggiunto al database.
  • Un documento esistente viene eliminato dal database.
  • Viene aggiornato un documento esistente nel database.

Gli indici delle viste vengono ricostruiti interamente quando la definizione della vista cambia, o quando cambia un'altra definizione di vista nello stesso documento di progettazione. La ricostruzione assicura che le modifiche alle definizioni delle viste si riflettano negli indici delle viste. Per garantire che la ricostruzione avvenga, viene creata una 'impronta digitale' della definizione di vista ogni volta che il documento di progettazione viene aggiornato. Se l'impronta digitale cambia, gli indici delle viste vengono ricostruiti.

Le ricostruzioni degli indici delle viste avvengono quando si modifica una vista qualsiasi tra tutte quelle definite nel documento di progettazione. Ad esempio, se si dispone di un documento di progettazione con tre viste e si aggiorna il documento di progettazione, tutti e tre gli indici delle viste all'interno del documento di progettazione vengono ricostruiti. Se volete modificare un documento di progettazione per un database più grande, date un'occhiata a Guida alla gestione dei documenti di progettazione.

Se il database è stato aggiornato di recente, i risultati potrebbero essere ritardati quando si accede alla vista. Il ritardo è influenzato dal numero di modifiche apportate al database, e se l'indice della vista non è aggiornato perché il contenuto del database è stato modificato.

Non è possibile eliminare questi ritardi. Per i database appena creati, si potrebbero ridurre i ritardi creando la definizione della vista nel documento di progettazione del database prima di inserire o aggiornare i documenti. La creazione della definizione di vista nel documento di progettazione provoca aggiornamenti incrementali dell'indice quando vengono inseriti i documenti.

Se la velocità di risposta è più importante della disponibilità di dati aggiornati, un'alternativa è quella di consentire agli utenti di accedere a una vecchia versione dell'indice della vista. Per consentire l'accesso a una vecchia versione dell'indice della vista, utilizzare il parametro update query string quando si effettua una query della vista.

Se si desidera salvare le vecchie versioni degli indici senza utilizzare il processore di indicizzazione, è possibile interrompere la creazione di tutti gli indici impostando "autoupdate": {"indexes": false}. In alternativa, è possibile impedire l'aggiornamento automatico delle viste aggiungendo una delle seguenti opzioni a un documento di progettazione. È possibile impedire l'indicizzazione di tutti i tipi di indice se si imposta "autoupdate": false.

Vedi i seguenti esempi:

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

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

Visualizza la freschezza

Per impostazione predefinita, tutti i risultati degli indici riflettono lo stato attuale del database database. IBM Cloudant costruisce i suoi indici automaticamente e in modo asincrono in background. Questa pratica di solito significa che l'indice è completamente aggiornato quando viene interrogato. Se no, per impostazione predefinita, IBM Cloudant applica gli aggiornamenti rimanenti al momento della query aggiornamenti rimanenti al momento della query.

IBM Cloudant fornisce alcuni parametri, descritti di seguito per modificare questo comportamento. Si sconsiglia l'uso di gli effetti collaterali sono in genere superiori ai benefici.

Parametri

L'opzione update indica se si è disposti ad accettare i risultati della vista senza attendere l'aggiornamento della vista. Il valore predefinito è true, il che significa che la vista viene aggiornata prima che i risultati vengano restituiti. Il valore lazy significa che i risultati vengono restituiti prima che che la vista sia aggiornata, ma che la vista debba essere aggiornata comunque.

Sebbene IBM Cloudant si sforzi di mantenere gli indici aggiornati in background, non esiste alcuna garanzia su quanto non sia aggiornata la vista quando viene interrogata con update=false o con update=lazy.

L'opzione stable indica se si preferisce ottenere risultati da un singolo insieme coerente di frammenti. Il valore false significa che tutte le repliche di shard disponibili vengono interrogate e IBM Cloudant utilizza la risposta più veloce risposta. Al contrario, l'impostazione stable=true forces the database to use just one replica of the index.

L'uso di stable=true può causare un'elevata latenza, poiché consulta solo una delle copie dell'indice, anche se le altre copie risponderebbero più velocemente risponderebbero più velocemente.

Combinazione di parametri

Se si specifica stable=false e update=false, si nota una maggiore incoerenza tra i risultati, anche se per la stessa query e senza modifiche al database. Si sconsiglia questa combinazione a meno che a meno che non siate sicuri che il vostro sistema possa tollerare questo comportamento.

Ordinamento delle righe restituite

I dati restituiti da una query di visualizzazione sono sotto forma di array. Ogni elemento dell'array viene ordinato utilizzando l'ordinamento standard UTF-8. L'ordinamento viene applicato alla chiave definita nella funzione di visualizzazione.

L'ordine di base dell'uscita è mostrato nella tabella seguente:

Ordine delle righe restituite
Valore Ordina
null Primo
false
true
Numeri
Testo (minuscolo)
Testo (maiuscolo)
Array (in base ai valori di ciascun elemento, utilizzando l'ordine indicato in questa tabella)
Oggetti (in base ai valori delle chiavi, in ordine di chiave utilizzando l'ordine indicato in questa tabella) Ultimo

È possibile invertire l'ordine delle informazioni di visualizzazione restituite impostando il descending valore della query true.

Quando si invia una richiesta di visualizzazione che specifica il parametro keys, i risultati vengono restituiti nello stesso ordine dell'array keys fornito.

Vedere l'esempio di utilizzo di HTTP per richiedere i record in ordine inverso:

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

Vedere l'esempio di richiesta dei record in ordine inverso.

Le librerie client utilizzano il metodo POST invece di GET perché hanno un comportamento simile.

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

Il precedente esempio di Go richiede il seguente blocco di importazione:

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

Tutti gli esempi Go richiedono l'iniziazione dell'oggetto service. Per ulteriori informazioni, consultare la sezione Autenticazione della documentazione API per gli esempi.

Vedere l'esempio di risposta per la richiesta dei record in ordine inverso:

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

Specificare i tasti di inizio e fine

Gli argomenti start_key e end_key query possono essere usati per specificare l'intervallo di valori che vengono restituiti quando si interroga la vista.

La direzione di ordinamento viene sempre applicata per prima. Successivamente, viene applicato un filtro utilizzando gli argomenti start_key e end_key della query. È possibile che nessuna riga corrisponda all'intervallo di chiavi se i piani di ordinamento e di filtro non hanno senso quando vengono combinati.

Si veda l'esempio di utilizzo di HTTP per effettuare una query globale che includa start_key e end_key argomenti della query:

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

Vedere l'esempio di una query globale che include gli argomenti start_key e end_key della query.

Le librerie client utilizzano il metodo POST invece di GET perché hanno lo stesso 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))

Il precedente esempio di Go richiede il seguente blocco di importazione:

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

Tutti gli esempi Go richiedono l'iniziazione dell'oggetto service. Per ulteriori informazioni, consultare la sezione Autenticazione della documentazione API per gli esempi.

Ad esempio, se si dispone di un database che restituisce un risultato quando si utilizza un start_key di alpha e un end_key di beta, si otterrebbe un errore 400 (Bad request) con un ordine invertito. Il motivo è che le voci della vista sono invertite prima dell'applicazione del filtro chiave.

Si veda l'esempio che utilizza HTTP per illustrare perché l'inversione dell'ordine di start_key e end_key potrebbe restituire un errore di analisi della query:

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

Si veda l'esempio che illustra perché l'inversione dell'ordine di start_key e end_key potrebbe causare un errore 400.

Le librerie client utilizzano il metodo POST invece di GET perché hanno lo stesso 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))

Il precedente esempio di Go richiede il seguente blocco di importazione:

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

Tutti gli esempi Go richiedono l'iniziazione dell'oggetto service. Per ulteriori informazioni, consultare la sezione Autenticazione della documentazione API per gli esempi.

Il end_key di beta viene visto prima del start_key di alpha, con conseguente errore di parsing della query.

La soluzione consiste nell'invertire non solo l'ordine di ordinamento, ma anche i valori dei parametri start_key e end_key.

L'esempio seguente mostra il filtraggio corretto e l'inversione dell'ordine di uscita, utilizzando l'argomento descending query, e invertendo gli argomenti start_key e end_key della query.

Vedere l'esempio che utilizza HTTP per applicare filtri e ordinamenti corretti a una query globale:

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

Vedere l'esempio per applicare i filtri e gli ordinamenti corretti a una query globale.

Le librerie client utilizzano il metodo POST invece di GET perché hanno lo stesso 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))

Il precedente esempio di Go richiede il seguente blocco di importazione:

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

Tutti gli esempi Go richiedono l'iniziazione dell'oggetto service. Per ulteriori informazioni, consultare la sezione Autenticazione della documentazione API per gli esempi.

Interrogare una vista utilizzando un elenco di chiavi

È possibile eseguire una query anche fornendo un elenco di chiavi da utilizzare.

La richiesta di informazioni da un database in questo modo usa il documento di progettazione $VIEW_NAME specificato $DDOC Come il parametro keys per il metodo GET, si può usare il metodo POST per specificare le chiavi da usare per recuperare i risultati della vista. In all other aspects, the POST method is the same as the GET API request. In particolare, è possibile utilizzare qualsiasi parametro della query sia nella stringa della query che nel corpo del JSON.

Vedere l'esempio di richiesta HTTP che restituisce tutti gli utenti in cui la chiave della vista corrisponde a amelie.smith@aol.com o 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"
  ]
}

Si veda l'esempio di una query globale che restituisce tutti gli utenti (dove la chiave per le corrispondenze della vista è o amelie.smith@aol.com o 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))

Il precedente esempio di Go richiede il seguente blocco di importazione:

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

Tutti gli esempi Go richiedono l'iniziazione dell'oggetto service. Per ulteriori informazioni, consultare la sezione Autenticazione della documentazione API per gli esempi.

La risposta contiene le informazioni standard sulla vista, ma solo i documenti in cui le chiavi corrispondono.

Vedere l'esempio di risposta dopo aver eseguito una query utilizzando un elenco di chiavi:

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

Recupero di più documenti

La sezione seguente tratta una richiesta POST di molti documenti da un database.

Per un'applicazione client, questa tecnica è più efficiente rispetto all'utilizzo di più GET richieste API.

Tuttavia, include_docs=true potrebbe richiedere un tempo di elaborazione aggiuntivo rispetto all'accesso alla vista da sola.

Il motivo è che usando include_docs=true in una query di visualizzazione, tutti i documenti dei risultati devono essere recuperati per costruire la risposta per l'applicazione client. In effetti, viene eseguita un'intera serie di richieste di documenti, ognuna delle quali compete per le risorse con altre richieste di applicazioni GET

Un modo per mitigare questo effetto è recuperare i risultati direttamente dal file indice della vista. Omettere include_docs=true per recuperare i risultati direttamente dal file indice della vista. Invece, nella funzione map di un documento di progettazione, emettere i campi richiesti come valore per l'indice della vista.

Ad esempio, nella funzione mappa si potrebbe utilizzare la seguente specifica di progettazione:

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

Vedere l'esempio di richiesta che utilizza HTTP per ottenere il contenuto completo dei documenti che corrispondono alle chiavi elencate all'interno di una partizione:

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

Vedere la richiesta di esempio per ottenere il contenuto completo dei documenti che corrispondono alle chiavi elencate all'interno della partizione 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))

Il precedente esempio di Go richiede il seguente blocco di importazione:

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

Tutti gli esempi Go richiedono l'iniziazione dell'oggetto service. Per ulteriori informazioni, consultare la sezione Autenticazione della documentazione API per gli esempi.

Vedere l'esempio di risposta (abbreviata), che restituisce il documento completo per ogni apparecchio che corrisponde a una chiave fornita:

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