Parametri di query

I parametri della query modificano l'output delle richieste di IBM Cloudant Query, alterando l'ordine, i campi restituiti o la paginazione delle risposte. I parametri vengono forniti nella query, accanto al campo selector.

Panoramica dei parametri

Questo documento JSON utilizza tutti i parametri di query disponibili:

{
  // Query selector
	"selector": {
		"year": {
			"$gt": 2010
		}
	},
	// Specify fields to return
	"fields": ["_id", "_rev", "year", "title"],
	// Specify sort order
	"sort": [{"year": "asc"}],
	// Return a maximum number of results
	"limit": 10,
	// Start returning results from a previous bookmark (pagination)
	"bookmark":"g1AAAAA-eJzLYWBgYMpgSmHgKy5JLCrJTq2MT8lPzkzJB"
	// Hint to use a specific index for a query
	"use_index": "_design/32372935e14bed00cc6db4fc9efca0f1537d34a8",
	// Disallow using a different index than the specified index
  "allow_fallback": false
	}

Specificare i campi da restituire

È possibile specificare quali campi vengono restituiti per un documento quando si seleziona da un database. Questo può offrire dei vantaggi:

  • I risultati sono limitati solo alle parti del documento necessarie per la vostra applicazione.
  • Una riduzione delle dimensioni della risposta.

I campi da restituire sono specificati utilizzando l'array fields nella query. I nomi dei campi forniti possono utilizzare la notazione punteggiata per accedere ai sottocampi.

Questa query restituirà solo i quattro campi specificati nei documenti dei risultati:

{
	"selector": {
		"Actor_name": "Robert De Niro"
	},
	"fields": [
		"Actor_name",
		"Movie_year",
		"_id",
		"_rev"
	]
}

Nella risposta vengono inclusi solo i campi del filtro specificato. _id o altri campi di metadati non vengono inclusi automaticamente.

Ordinamento dei risultati

Usare il campo sort in una query per specificare come vengono ordinati i risultati restituiti. Il campo sort contiene un elenco di coppie di nomi di campi e direzioni, espresse come array. La prima coppia di nomi di campo e di direzione è il livello superiore di ordinamento. Altre coppie, se fornite, specificano il livello successivo di ordinamento.

Il campo di ordinamento può essere qualsiasi campo. Se necessario, utilizzare la notazione punteggiata per i sottocampi.

Il valore della direzione è asc per la salita e desc per la discesa:

"sort": [{ "fieldName1": "desc" }, { "fieldName2": "desc" }]

Se si esclude il valore della direzione, viene utilizzato il valore predefinito asc. Per l'ordinamento ascendente, si può usare la seguente abbreviazione:

"sort": [ "fieldName1", "fieldName2" ]

Un'esigenza tipica è quella di cercare un contenuto utilizzando un selettore, quindi ordinare i risultati in base al campo specificato, nella direzione preferita.

Per utilizzare l'ordinamento, è necessario definire un indice contenente i campi di ordinamento. Se si utilizza l'indice json, i campi devono essere specificati nello stesso ordine dell'ordinamento.

Attualmente, IBM Cloudant Query non supporta campi multipli con ordini diversi, quindi la direzione deve essere o tutta ascendente o tutta discendente.

Se la direzione è ascendente, si può usare una stringa invece di un oggetto per specificare i campi di ordinamento.

Ordinamento tramite indici di testo

Per i nomi dei campi nelle query di ordinamento contro un indice text, quando non è possibile determinare il tipo di campo da ordinare, può essere necessario specificare un tipo di campo. Ad esempio:

"sort": [ { "<fieldname>:string": "asc" } ]
Quando specificare il tipo di campo
Quale indice viene utilizzato dalla query? Requisiti del tipo di campo
Indice JSON Nessuno
Indice testuale di tutti i campi in tutti i documenti Specificare il campo di ordinamento nella query se il database contiene documenti in cui il campo di ordinamento ha un solo tipo. Inoltre, specificare il campo di ordinamento nella query se questa contiene documenti in cui il campo di ordinamento ha un tipo diverso.
Qualsiasi altro indice di testo Specificare il tipo di tutti i campi di ordinamento della query.

Un indice di testo di tutti i campi in tutti i documenti viene creato quando si utilizza la sintassi: "index": {}.

L'ordine di ordinamento non è definito quando i campi contengono tipi di dati diversi. Questa caratteristica rappresenta un'importante differenza tra gli indici di testo e quelli di vista. Il comportamento dell'ordinamento per i campi con tipi di dati diversi potrebbe cambiare nelle versioni future.

Paginazione

IBM Cloudant La query supporta la paginazione in base al campo segnalibro. Ogni risposta di _find contiene un segnalibro - un token che IBM Cloudant usa per determinare da dove ripartire quando si effettuano le successive interrogazioni. Per ottenere il successivo per ottenere il prossimo set di risultati della query, aggiungere il segnalibro ricevuto nella risposta precedente alla richiesta successiva. Ricordate di mantenere il selettore invariato, altrimenti otterrete risultati inaspettati. Per impaginare all'indietro, si può usare un segnalibro precedente per tornare alla serie precedente di risultati.

La presenza di un segnalibro non garantisce maggiori risultati. È possibile verificare se se si è alla fine del set di risultati, confrontando il numero di risultati restituiti con la dimensione della pagina richiesta richiesta. Se i risultati restituiti sono inferiori al limite, non sono stati restituiti altri risultati nel set di risultati.

Suggerimento di utilizzo di un indice specifico

Per indicare a una query di utilizzare un indice specifico, aggiungere il parametro use_index alla query. Si tratta di un suggerimento; se l'indice non può essere utilizzato per la query, verrà utilizzato un indice alternativo.

Il valore del parametro use_index assume uno dei seguenti formati:

  • "use_index": "$DDOC"
  • "use_index": ["$DDOC","$INDEX_NAME"]

Questa query di esempio mostra il suggerimento di un indice specifico con use_index:

{
	"selector": {
		"$text": "Pacino",
		"year": 2010
	},
	"use_index": "_design/32372935e14bed00cc6db4fc9efca0f1537d34a8"
}

Forzare l'uso di un indice specifico

Combinare il parametro allow_fallback con use_index per forzare l'uso di un indice specifico. Se l'indice non può essere utilizzato per la query, questa restituirà una risposta di errore.

L'uso di "allow_fallback": false senza specificare use_index impedisce l'uso dell'indice incorporato _all_docs.

Questo esempio di query mostra la forzatura di un indice specifico utilizzando allow_fallback con use_index:

{
	"selector": {
		"$text": "Pacino",
		"year": 2010
	},
	"use_index": "_design/32372935e14bed00cc6db4fc9efca0f1537d34a8",
  "allow_fallback": false
}