Come funzionano i documenti di progettazione

IBM® Cloudant® for IBM Cloud® legge campi e valori specifici dei documenti di progettazione come funzioni. I documenti di progetto vengono utilizzati per creare indici e convalidare gli aggiornamenti.

Ogni documento di progettazione definisce indici partizionati o globali, che sono controllati dal campo options.partitioned. Un indice partizionato consente solo le interrogazioni su una singola partizione di dati in un database partizionato. Un indice globale consente l'esecuzione di query su tutti i dati all'interno di un database, a un costo di latenza e velocità di trasmissione su un indice partizionato.

Creazione o aggiornamento di un documento di progettazione

Metodo: PUT /$DATABASE/_design/$DDOC
Richiesta: JSON delle informazioni del documento di progettazione.
Risposta: Stato JSON.
Ruoli consentiti: _admin

Per creare un documento di progettazione, caricarlo nel database specificato.

In questi esempi, $VARIABLES potrebbe fare riferimento a documenti standard o di progettazione. Per distinguerli, i documenti standard hanno un _id indicato da $DOCUMENT_ID, mentre i documenti di progetto hanno un _id indicato da $DDOC.

Un ID del documento di progettazione non include mai una chiave di partizione indipendentemente dal tipo di partizionamento del database. La chiave di partizioni non è inclusa perché gli indici inclusi in un documento di progettazione si applicano a tutte le partizioni in un database partizionato.

Se un documento di progettazione viene aggiornato, IBM Cloudant cancella gli indici della versione precedente e li ricrea da zero. Se è necessario modificare un documento di progettazione per un database più grande, consultare la Guida alla gestione dei documenti di progettazione.

La struttura di un documento di progettazione include le parti seguenti:

_id

ID documento di progettazione. Questo ID è sempre con prefisso _design e mai include una chiave di partizione, indipendentemente dal tipo di partizionamento del database.

_rev

Revisione documento di progettazione.

Opzioni

Contiene opzioni per questo documento di progettazione.

Partizionato (facoltativo, booleano): Determina se questo documento di progettazione descrive gli indici partizionati o globali. Per ulteriori informazioni, consultare Il campo options.partitioned.

Viste (facoltativo)

Un oggetto che descrive viste MapReduce.

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

Riduci (facoltativo)

Funzione di riduzione per la vista.

Indici (facoltativo)

Un oggetto che descrive gli indici di ricerca.

Nome indice

(Uno per ogni indice)- Definizione indice.

Analizzatore: Oggetto che descrive il programma di analisi da utilizzare o un oggetto con i seguenti campi:

Nome

Nome del programma di analisi. I valore validi sono standard, email, keyword, simple, whitespace, classic e perfield.

Parole non significative (facoltativo)

Un array di parole non significative. Le parole non significative sono parole che non devono essere indicizzate. Se questo array viene specificato, sovrascrive l'elenco predefinito di parole non significative. L'elenco predefinito di stop word dipende dal programma di analisi. Il programma di analisi standard include il seguente elenco di stop word: 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.

Predefinito (per il programma di analisi per campo)

Lingua predefinita da utilizzare se non viene specificata alcuna lingua per il campo.

Campi (per il programma di analisi per campo): Un oggetto che specifica la lingua da utilizzare per analizzare ciascun campo dell'indice. I nomi di campo nell'oggetto corrispondono ai nomi di campo nell'indice, ossia, il primo parametro della funzione di indice. I valori dei campi sono le lingue da utilizzare, ad esempio english.
Indice: Funzione che gestisce l'indicizzazione.

Filtri (facoltativi, non consentiti quando partitioned è true)

Funzioni filtro.

Nome funzione (uno per ogni funzione): Definizione di funzione.

Validate_doc_update (facoltativo, non consentito quando partitioned è true)

Aggiorna funzione di convalida.

Il campo `options.partitioned`

Questo campo imposta se l'indice creato è un indice partizionato o globale.

Questo campo può assumere i seguenti valori:

Valori per il campo options.partitioned
Valore	Descrizione	Note
`true`	Creare l'indice come partizionato.	Può essere utilizzato solo in un database con partizioni.
`false`	Creare l'indice come globale.	Può essere utilizzato in qualsiasi database.

Il valore predefinito segue l'impostazione partitioned per il database:

Impostazioni di partizione
Il database è partizionato?	Valore `partitioned` predefinito	Valori consentiti
Sì	`true`	`true`, `false`
No	`false`	`false`

Copia di un documento di progettazione

È possibile copiare l'ultima versione di un documento di progettazione in un nuovo documento specificando il documento di base e il documento di destinazione. La copia viene richiesta utilizzando il metodo di richiesta COPY.

COPY è un comando non standard di HTTP.

Il seguente esempio richiede che IBM Cloudant copi il documento di progetto allusers al nuovo documento di progetto copyOfAllusers e produca una risposta che includa l'ID e la revisione del nuovo documento.

La copia di un documento di progettazione non ricostruisce automaticamente gli indici della vista. Come altre viste, queste viste vengono ricreate la prima volta che si accede alla nuova vista.

Si veda il seguente esempio di comando per copiare un documento di progettazione utilizzando HTTP:

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

Fare riferimento al seguente comando di esempio per copiare un documento di progettazione:

Gli SDK di IBM Cloudant non supportano attualmente il metodo HTTP COPY.

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

Vedere la seguente risposta di esempio alla richiesta di copia:

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

La struttura del comando di copia

Metodo: COPY /$DATABASE/_design/$DDOC
Richiesta: Nessuno.
Risposta: JSON che descrive il nuovo documento e la revisione.
Ruoli consentiti: _design

Argomenti query

Argomento

rev

Descrizione: Revisione da cui copiare.
Facoltativo: Sì.
Immettere: Stringa.

Intestazioni HTTP

Intestazione

Destination

Descrizione: Documento di destinazione (e revisione facoltativa)
Facoltativo: Num.

Il documento di progettazione di origine è specificato nella riga della richiesta, mentre l'intestazione Destination HTTP della richiesta specifica il documento di destinazione.

Copia da una revisione specifica

Per copiare una specifica versione, aggiungere l'argomento rev alla stringa di query.

Il nuovo documento di progettazione viene creato utilizzando la revisione specificata del documento origine.

Si veda il seguente esempio di comando per copiare una revisione specifica del documento di progettazione utilizzando HTTP:

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

Consultare il comando di esempio riportato di seguito per copiare una revisione specifica del documento di progettazione utilizzando la riga comandi:

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

Copia in un documento di progettazione esistente

Per sovrascrivere o copiare un documento esistente, specificare la stringa di revisione corrente per il documento di destinazione utilizzando il parametro utilizzando il parametro rev alla stringa di intestazione Destination HTTP.

Si veda il seguente esempio di comando per sovrascrivere una copia esistente del documento di progettazione utilizzando HTTP:

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

Fare riferimento al seguente comando di esempio per sovrascrivere una copia esistente del documento di progettazione utilizzando la riga comandi:

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

Il valore di ritorno è l'ID e la nuova revisione del documento copiato.

Fare riferimento alla seguente risposta di esempio per sovrascrivere una copia esistente del documento di progettazione:

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

Eliminazione di un documento di progettazione

È possibile eliminare un documento di progettazione esistente. L'eliminazione di un documento di progettazione elimina anche tutti gli indici della vista associati e recupera lo spazio corrispondente sul disco per gli indici in questione.

Per eliminare correttamente un documento di progettazione, è necessario specificare la revisione corrente del documento di progettazione utilizzando l'argomento della query rev.

Si veda il seguente esempio di comando per eliminare un documento di progettazione utilizzando HTTP:

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

Consultare i seguenti esempi per eliminare un documento di progettazione:

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

L'esempio Go precedente richiede il seguente blocco di importazione:

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

Vedi la seguente risposta di esempio che include l'ID documento e la revisione eliminati:

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

La struttura del comando delete

Metodo: DELETE /db/_design/$DDOC
Richiesta: Nessuno.
Risposta: JSON del documento di progettazione eliminato.
Ruoli consentiti: _design

Argomenti query

Argomento

rev

Descrizione: Revisione corrente del documento per la convalida.
Facoltativo: Sì, se l'intestazione If-Match esiste.
Immettere: Stringa.

Intestazioni HTTP

Intestazione

If-Match

Descrizione: Revisione corrente del documento per la convalida.
Facoltativo: Sì, se l'argomento della query rev esiste.

Viste

Un uso importante dei documenti di progettazione è per la creazione di viste. Per ulteriori informazioni sulla creazione di viste, consultare Viste(MapReduce).

Indici

Tutte le query operano su indici predefiniti definiti nei documenti di progetto. Tali indici sono definiti nel seguente elenco:

Ad esempio, per creare un documento di progettazione utilizzato per la ricerca, è necessario verificare che due condizioni siano vere:

Il documento è stato definito come documento di progetto quando è stato avviato _id con _design/.
Hai creato un indice di ricerca all'interno del documento, aggiornando il documento con il campo appropriato oppure creando un nuovo documento che include l'indice di ricerca.

Non appena il documento di progettazione dell'indice di ricerca esiste e l'indice viene creato, è possibile eseguire delle query utilizzandolo.

Note generali sulle funzioni nei documenti di progettazione

Le funzioni nei documenti di progettazione vengono eseguite su più nodi per ciascun documento e possono essere eseguite più volte. Per evitare incongruenze, devono essere idempotenti, il che significa che devono comportarsi in modo identico quando vengono eseguiti più volte o su nodi diversi. In particolare, è necessario non utilizzare funzioni che generano numeri casuali o restituiscono l'ora corrente.

Funzioni di filtro

I documenti di progettazione con options.partitioned impostato su true non possono contenere un campo filters.

Le funzioni filtro sono documenti di progettazione che filtrano il feed delle modifiche. Funzionano applicando test a ciascuno degli oggetti inclusi nel feed delle modifiche.

Se uno dei test di funzione ha esito negativo, l'oggetto viene "rimosso" o "filtrato" dal feed. Se la funzione restituisce un risultato true quando viene applicata a una modifica, la modifica rimane nel feed. In altre parole, le funzioni di filtro "rimuovi" o "ignora" le modifiche che non si desidera monitorare.

Le funzioni di filtro possono essere utilizzate anche per modificare un'attività di replica .

Le funzioni di filtro richiedono due argomenti: doc e req.

L'argomento doc rappresenta il documento verificato per il filtro.

L'argomento req include ulteriori informazioni sulla richiesta. Con questo argomento, è possibile creare funzioni di filtro che sono più dinamiche perché si basano su più fattori come i parametri di query o il contesto utente.

Ad esempio, si possono controllare alcuni aspetti dei test delle funzioni di filtro utilizzando valori dinamici forniti come parte della richiesta HTTP. Tuttavia, in molti casi di utilizzo della funzione di filtro, viene utilizzato solo il parametro doc.

Consultare il seguente documento di progettazione di esempio che include una funzione di filtro:

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

Si veda il seguente esempio di funzione di 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!
}

Modifica funzioni di filtro feed

Per applicare una funzione filtro al feed delle modifiche, includere il parametro filter nella query _changes, fornendo il nome del filtro da utilizzare.

Si veda l'esempio seguente di una funzione di filtro applicata a una query di _changes utilizzando HTTP:

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

Consultare i seguenti esempi di una funzione di filtro applicata a una query _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))

L'esempio Go precedente richiede il seguente blocco di importazione:

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

Argomento `req` della funzione di filtro

L'argomento req consente di accedere agli aspetti della richiesta HTTP utilizzando la proprietà query.

Si veda il seguente esempio di fornitura di un argomento req utilizzando HTTP:

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

Consultare il seguente esempio di fornitura di un argomento req:

Gli SDK IBM Cloudant non supportano attualmente l'opzione status per la richiesta _changes.

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

Consultare il seguente esempio di filtro utilizzando un argomento req fornito:

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

Funzioni di filtro predefinite

Sono disponibili diverse funzioni di filtro predefinite:

_design: Accetta solo modifiche ai documenti di progetto.
_doc_ids: Accetta solo le modifiche per i documenti il cui ID è specificato nel parametro doc_ids o nel documento JSON fornito.
_selector: Accetta solo le modifiche per i documenti che corrispondono a un selettore specificato definito utilizzando la stessa sintassi del selettore descritta nella sezione Richiesta, utilizzata per _find.
_view: Con questa funzione, è possibile utilizzare una funzione mappa esistente come filtro.

Il filtro `_design`

Il filtro _design accetta modifiche solo per i documenti di progettazione all'interno del database richiesto.

Il filtro non richiede alcun argomento.

Le modifiche vengono elencate per tutti i documenti di progettazione all'interno del database.

Si veda il seguente esempio di applicazione del filtro _design utilizzando HTTP:

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

Consultare le seguenti applicazioni di esempio del 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))

L'esempio Go precedente richiede il seguente blocco di importazione:

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

Vedi la seguente risposta di esempio (abbreviata) dopo aver applicato il 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"
    },
    ...
  ]
}

Il filtro `_doc_ids`

Il filtro _doc-ids accetta solo le modifiche per i documenti con ID specificati. Gli ID sono specificati in un parametro doc_ids o all'interno di un documento JSON fornito come parte della richiesta originale.

Si veda il seguente esempio di applicazione del filtro _doc_ids utilizzando HTTP:

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

Consultare le seguenti applicazioni di esempio del 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))

L'esempio Go precedente richiede il seguente blocco di importazione:

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

Vedi il seguente documento JSON di esempio che elenca gli ID documento da mettere in corrispondenza durante il filtraggio:

{
  "doc_ids": [
    "ExampleID"
  ]
}

Vedi la seguente risposta di esempio (abbreviata) dopo aver filtrato per _docs_ids:

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

Il filtro `_selector`

Il filtro _selector accetta solo modifiche per i documenti che corrispondono a un selettore specificato, definito utilizzando la stessa sintassi del selettore utilizzata per _find.

Per ulteriori esempi che mostrano l'utilizzo di questo filtro, vedi le informazioni sulla sintassi del selettore.

Si veda il seguente esempio di applicazione del filtro _selector utilizzando HTTP:

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

Consultare le seguenti applicazioni di esempio del 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))

L'esempio Go precedente richiede il seguente blocco di importazione:

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

Vedi il seguente documento JSON di esempio che include l'espressione del selettore da utilizzare durante il filtro:

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

Vedi la seguente risposta di esempio (abbreviata) dopo aver filtrato utilizzando un selettore:

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

Il filtro `_view`

Utilizzando il filtro _view, è possibile utilizzare una funzione di mappatura esistente come filtro.

La funzione di associazione potrebbe emettere un output come risultato dell'elaborazione di un documento specifico. Quando si verifica questa situazione, il filtro considera il documento consentito e lo include nell'elenco dei documenti modificati.

Si veda il seguente esempio di applicazione del filtro _view utilizzando HTTP:

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

Consultare le seguenti applicazioni di esempio del 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))

Consultare la seguente risposta di esempio (abbreviata) dopo aver filtrato utilizzando una funzione di mappa:

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

Aggiorna programmi di convalida

I documenti di progettazione con options.partitioned impostato su true non possono contenere un campo validate_doc_update.

I programmi di convalida degli aggiornamenti determinano se un documento deve essere scritto su disco quando si tentano gli inserimenti e gli aggiornamenti. Non richiedono una query perché implicitamente vengono eseguiti durante questo processo. Se una modifica viene rifiutata, il programma di convalida dell'aggiornamento risponde con un errore personalizzato.

I programmi di convalida degli aggiornamenti richiedono quattro argomenti:

Argomenti per il validatore di aggiornamento
Argomento	Scopo
`newDoc`	La versione del documento passata nella richiesta.
`oldDoc`	La versione del documento attualmente nel database o `null` se non esiste.
`secObj`	L' oggetto di sicurezza per il database.
`userCtx`	Contesto relativo all'utente attualmente autenticato, ad esempio `name` e `roles`.

I programmi di convalida degli aggiornamenti non si applicano quando un documento di progetto viene aggiornato da un amministratore. Questa pratica garantisce che gli amministratori non possano mai bloccarsi accidentalmente.

Consultare il seguente documento di progettazione di esempio con un programma di convalida dell'aggiornamento:

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

Consultare il seguente esempio di un programma di convalida dell'aggiornamento:

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

Vedere la seguente risposta di esempio da un programma di convalida dell'aggiornamento:

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

Richiamo delle informazioni su un documento di progettazione

Due endpoint forniscono ulteriori informazioni sui documenti di progettazione: _info e _search_info.

L'endpoint `_info`

L'endpoint _info restituisce le informazioni su uno specifico documento di progettazione, incluso l'indice di visualizzazione, la dimensione dell'indice di vista e lo stato del documento di progettazione e le relative informazioni sull'indice di visualizzazione.

Metodo: GET /db/_design/$DDOC/_info
Richiesta: Nessuno
Risposta: Il JSON che contiene le informazioni del documento di progettazione.
Ruoli consentiti: _reader

Si veda il seguente esempio di recupero di informazioni sul documento di progettazione recipesdd dall'interno del database recipes utilizzando HTTP:

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

Consultare i seguenti esempi di richiamo delle informazioni sul documento di progettazione recipesdd dall'interno del database recipes:

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

getDesignDocumentInformationOptions := service.NewGetDesignDocumentInformationOptions(
  "recipes",
  "recipesdd",
)
designDocumentInformation, response, err := service.GetDesignDocumentInformation(getDesignDocumentInformationOptions)
if err != nil {
  panic(err)
}
b, _ := json.MarshalIndent(designDocumentInformation, "", "  ")
fmt.Println(string(b))

from ibmcloudant.cloudant_v1 import CloudantV1
service = CloudantV1.new_instance()
response = service.get_design_document_information(
  db='recipes',
  ddoc='recipesdd'
).get_result()
print(response)

import com.ibm.cloud.cloudant.v1.Cloudant;
import com.ibm.cloud.cloudant.v1.model.DesignDocumentInformation;
import com.ibm.cloud.cloudant.v1.model.GetDesignDocumentInformationOptions;
Cloudant service = Cloudant.newInstance();
GetDesignDocumentInformationOptions informationOptions =
    new GetDesignDocumentInformationOptions.Builder()
        .db("recipes")
        .ddoc("recipesdd")
        .build();
DesignDocumentInformation response =
    service.getDesignDocumentInformation(informationOptions).execute()
        .getResult();
System.out.println(response);

const { CloudantV1 } = require('@ibm-cloud/cloudant');
const service = CloudantV1.newInstance({});
service.getDesignDocumentInformation({
  db: 'recipes',
  ddoc: 'recipesdd'
}).then(response => {
  console.log(response.result);
});

La risposta JSON include i seguenti campi individuali:

name

Nome o ID del documento di progettazione.

view_index

Visualizza indice

compact_running: Indica se una routine di compattazione viene eseguita sulla vista.
disk_size: Dimensione in byte della vista come memorizzata sul disco.
language: Lingua utilizzata per definire le viste.
purge_seq: La sequenza di eliminazione elaborata.
signature: MD5 firma delle viste per il documento di progetto.
update_seq: La sequenza di aggiornamento del corrispondente database indicizzato.
updater_running: Indica se la vista è in fase di aggiornamento.
waiting_clients: Il numero di client in attesa di viste da questo documento di progettazione.
waiting_commit: Indica se il database sottostante ha commit in sospeso che devono essere elaborati.

Vedi la risposta di esempio seguente in 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
	}
}

L'endpoint `_search_info`

L'endpoint _search_info restituisce le informazioni su una specifica ricerca definita all'interno di un documento di progetto specifico.

Metodo: GET /db/_design/$DDOC/_search_info/yourSearch
Richiesta: Nessuno
Risposta: JSON che contiene informazioni sulla ricerca specificata.
Ruoli consentiti *: _reader

Si veda l'esempio seguente, in cui si ottengono informazioni sulla ricerca description, definita all'interno del documento di progettazione app memorizzato nel database foundbite, utilizzando HTTP:

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

Consultare i seguenti esempi di acquisizione delle informazioni relative all'indice di ricerca description, definito nel documento di progetto app memorizzato nel database foundbite:

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

from ibmcloudant.cloudant_v1 import CloudantV1
service = CloudantV1.new_instance()
response = service.get_search_info(
  db='foundbite',
  ddoc='app',
  index='description'
).get_result()
print(response)

import com.ibm.cloud.cloudant.v1.Cloudant;
import com.ibm.cloud.cloudant.v1.model.GetSearchInfoOptions;
import com.ibm.cloud.cloudant.v1.model.SearchInfoResult;
Cloudant service = Cloudant.newInstance();
GetSearchInfoOptions infoOptions =
    new GetSearchInfoOptions.Builder()
        .db("foundbite")
        .ddoc("app")
        .index("description")
        .build();
SearchInfoResult response =
    service.getSearchInfo(infoOptions).execute()
        .getResult();
System.out.println(response);

const { CloudantV1 } = require('@ibm-cloud/cloudant');
const service = CloudantV1.newInstance({});
service.getSearchInfo({
  db: 'foundbite',
  ddoc: 'app',
  index: 'description'
}).then(response => {
  console.log(response.result);
});

getSearchInfoOptions := service.NewGetSearchInfoOptions(
  "foundbite",
  "app",
  "description",
)
searchInfoResult, response, err := service.GetSearchInfo(getSearchInfoOptions)
if err != nil {
  panic(err)
}
b, _ := json.MarshalIndent(searchInfoResult, "", "  ")
fmt.Println(string(b))

La struttura JSON include i seguenti campi singoli:

name: Nome o ID della ricerca all'interno del documento di progettazione.
search_index: Indice di ricerca
pending_seq: Il numero di sequenze di modifiche nel database che hanno raggiunto l'indice Lucene, in memoria e su disco.
doc_del_count: Numero di documenti eliminati nell'indice.
doc_count: Numero di documenti presenti nell'indice.
disk_size: La dimensione dell'indice su disco, in byte.
committed_seq: Il numero di sequenza di modifiche nel database di cui è stato eseguito il commit nell'indice Lucene sul disco.

Vedi la risposta di esempio seguente in formato JSON:

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

Come funzionano i documenti di progettazione

Come funzionano i documenti di progettazione

Creazione o aggiornamento di un documento di progettazione

Il campo options.partitioned

Copia di un documento di progettazione

La struttura del comando di copia

Copia da una revisione specifica

Copia in un documento di progettazione esistente

Eliminazione di un documento di progettazione

La struttura del comando delete

Viste

Indici

Note generali sulle funzioni nei documenti di progettazione

Funzioni di filtro

Modifica funzioni di filtro feed

Argomento req della funzione di filtro

Funzioni di filtro predefinite

Il filtro _design

Il filtro _doc_ids

Il filtro _selector

Il filtro _view

Aggiorna programmi di convalida

Richiamo delle informazioni su un documento di progettazione

L'endpoint _info

L'endpoint _search_info

Il campo `options.partitioned`

Argomento `req` della funzione di filtro

Il filtro `_design`

Il filtro `_doc_ids`

Il filtro `_selector`

Il filtro `_view`

L'endpoint `_info`

L'endpoint `_search_info`