com.couchbase.client.protocol.views

Class Query

java.lang.Object

com.couchbase.client.protocol.views.Query

public class Query
extends java.lang.Object

The Query class allows custom view-queries to the Couchbase cluster. The Query class supports all arguments that can be passed along with a Couchbase view query. For example, this makes it possible to change the sorting order, query only a range of keys or include the full docs. By default, the full docs are not included and no reduce job is executed. Here is a short example on how to use the Query object - for more information on the allowed arguments see the corresponding setter method. // Run the reduce phase as well: Query query = new Query(); query.setReduce(true); // Include the full docs: Query query = new Query(); query.setIncludeDocs(true);

Constructor Summary

Constructors

Constructor and Description
Query() Create a new Query.

Method Summary

Modifier and Type	Method and Description
Query	copy() Copy the current Query object into another one.
protected java.lang.String	encode(java.lang.String source) Helper method to properly encode a string.
java.util.Map<java.lang.String,java.lang.Object>	getArgs() Helper method which collects all currently set arguments.
int	getLimit() Returns the currently set limit.
protected java.lang.String	quote(java.lang.String source) Helper method to properly quote the string if its a JSON string.
Query	setBbox(double lowerLeftLong, double lowerLeftLat, double upperRightLong, double upperRightLat) Sets the params for a spatial bounding box view query.
Query	setDebug(boolean debug) Enabled debugging on view queries.
Query	setDescending(boolean descending) Return the documents in descending by key order.
Query	setEndkeyDocID(java.lang.String endkeydocid) Stop returning records when the specified document ID is reached.
Query	setGroup(boolean group) Group the results using the reduce function to a group or single row.
Query	setGroupLevel(int grouplevel) Specify the group level to be used.
Query	setIncludeDocs(boolean include) If the full documents should be included in the result.
Query	setInclusiveEnd(boolean inclusiveend) Specifies whether the specified end key should be included in the result.
Query	setKey(ComplexKey key) Return only documents that match the specified key.
Query	setKey(java.lang.String key) Return only documents that match the specified key.
Query	setKeys(ComplexKey keys) Return only documents that match each of keys specified within the given array.
Query	setKeys(java.lang.String keys) Return only documents that match each of keys specified within the given array.
Query	setLimit(int limit) Limit the number of the returned documents to the specified number.
Query	setOnError(OnError onError) Sets the response in the event of an error.
Query	setRange(ComplexKey startkey, ComplexKey endkey) Returns records in the given key range.
Query	setRange(java.lang.String startkey, java.lang.String endkey) Returns records in the given key range.
Query	setRangeEnd(ComplexKey endkey) Stop returning records when the specified key is reached.
Query	setRangeEnd(java.lang.String endkey) Stop returning records when the specified key is reached.
Query	setRangeStart(ComplexKey startkey) Return records with a value equal to or greater than the specified key.
Query	setRangeStart(java.lang.String startkey) Return records with a value equal to or greater than the specified key.
Query	setReduce(boolean reduce) Explicitly enable/disable the reduce function on the query.
Query	setSkip(int skip) Skip this number of records before starting to return the results.
Query	setStale(Stale stale) Allow the results from a stale view to be used.
Query	setStartkeyDocID(java.lang.String startkeydocid) Return records starting with the specified document ID.
java.lang.String	toString() Returns the Query as a HTTP-compatible query string.
boolean	willIncludeDocs() Read if full documents will be included on the query.
boolean	willReduce() Read if reduce is enabled or not.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

Query

public Query()

Create a new Query.

Method Detail

setReduce

public Query setReduce(boolean reduce)

Explicitly enable/disable the reduce function on the query.

Parameters:

reduce - if reduce should be enabled or not.

Returns:

the Query object for proper chaining.

setLimit

public Query setLimit(int limit)

Limit the number of the returned documents to the specified number.

Parameters:

limit - the number of documents to return.

Returns:

the Query object for proper chaining.

setGroup

public Query setGroup(boolean group)

Group the results using the reduce function to a group or single row. Important: this setter and setGroupLevel(int) should not be used together in the same Query. It is sufficient to only set the grouping level only and use this setter in cases where you always want the highest group level implictly.

Parameters:

group - True when grouping should be enabled.

Returns:

the Query object for proper chaining.

setGroupLevel

public Query setGroupLevel(int grouplevel)

Specify the group level to be used. Important: setGroup(boolean) and this setter should not be used together in the same Query. It is sufficient to only use this setter and use setGroup(boolean) in cases where you always want the highest group level implictly.

Parameters:

grouplevel - How deep the grouping level should be.

Returns:

the Query object for proper chaining.

setIncludeDocs

public Query setIncludeDocs(boolean include)

If the full documents should be included in the result.

Parameters:

include - True when the full docs should be included in the result.

Returns:

the Query object for proper chaining.

setInclusiveEnd

public Query setInclusiveEnd(boolean inclusiveend)

Specifies whether the specified end key should be included in the result.

Parameters:

inclusiveend - True when the key should be included.

Returns:

the Query object for proper chaining.

setSkip

public Query setSkip(int skip)

Skip this number of records before starting to return the results.

Parameters:

skip - The number of records to skip.

Returns:

the Query object for proper chaining.

setStale

public Query setStale(Stale stale)

Allow the results from a stale view to be used. See the "Stale" enum for more information on the possible options. The default setting is "update_after"!

Parameters:

stale - Which stale mode should be used.

Returns:

the Query object for proper chaining.

setOnError

public Query setOnError(OnError onError)

Sets the response in the event of an error. See the "OnError" enum for more details on the available options.

Parameters:

onError - The appropriate error handling type.

Returns:

the Query object for proper chaining.

setDebug

public Query setDebug(boolean debug)

Enabled debugging on view queries.

Parameters:

debug - True when debugging should be enabled.

Returns:

the Query object for proper chaining.

setDescending

public Query setDescending(boolean descending)

Return the documents in descending by key order.

Parameters:

descending - True if the sort-order should be descending.

Returns:

the Query object for proper chaining.

setKey

public Query setKey(ComplexKey key)

Return only documents that match the specified key. The "key" param must be specified as a valid JSON string, but the ComplexKey class takes care of this. See the documentation of the ComplexKey class for more information on its usage.

Parameters:

key - The document key.

Returns:

the Query object for proper chaining.

setKey

public Query setKey(java.lang.String key)

Return only documents that match the specified key. Note that the given key string has to be valid JSON!

Parameters:

key - The document key.

Returns:

the Query object for proper chaining.

setKeys

public Query setKeys(ComplexKey keys)

Return only documents that match each of keys specified within the given array. The "keys" param must be specified as a valid JSON string, but the ComplexKey class takes care of this. See the documentation of the ComplexKey class for more information on its usage. Also, sorting is not applied when using this option.

Parameters:

keys - The document keys.

Returns:

the Query object for proper chaining.

setKeys

public Query setKeys(java.lang.String keys)

Return only documents that match each of keys specified within the given array. Note that the given key string has to be valid JSON! Also, sorting is not applied when using this option.

Parameters:

keys - The document keys.

Returns:

the Query object for proper chaining.

setStartkeyDocID

public Query setStartkeyDocID(java.lang.String startkeydocid)

Return records starting with the specified document ID.

Parameters:

startkeydocid - The document ID to match.

Returns:

the Query object for proper chaining.

setEndkeyDocID

public Query setEndkeyDocID(java.lang.String endkeydocid)

Stop returning records when the specified document ID is reached.

Parameters:

endkeydocid - The document ID that should be used.

Returns:

the Query object for proper chaining.

setRange

public Query setRange(java.lang.String startkey,
                      java.lang.String endkey)

Returns records in the given key range. Note that the given key strings have to be valid JSON!

Parameters:

startkey - The start of the key range.

endkey - The end of the key range.

Returns:

the Query object for proper chaining.

setRange

public Query setRange(ComplexKey startkey,
                      ComplexKey endkey)

Returns records in the given key range. The range keys must be specified as a valid JSON strings, but the ComplexKey class takes care of this. See the documentation of the ComplexKey class for more information on its usage.

Parameters:

startkey - The start of the key range.

endkey - The end of the key range.

Returns:

the Query object for proper chaining.

setRangeStart

public Query setRangeStart(java.lang.String startkey)

Return records with a value equal to or greater than the specified key. Note that the given key string has to be valid JSON!

Parameters:

startkey - The start of the key range.

Returns:

the Query object for proper chaining.

setRangeStart

public Query setRangeStart(ComplexKey startkey)

Return records with a value equal to or greater than the specified key. The range key must be specified as a valid JSON string, but the ComplexKey class takes care of this. See the documentation of the ComplexKey class for more information on its usage.

Parameters:

startkey - The start of the key range.

Returns:

the Query object for proper chaining.

setRangeEnd

public Query setRangeEnd(java.lang.String endkey)

Stop returning records when the specified key is reached. Note that the given key string has to be valid JSON!

Parameters:

endkey - The end of the key range.

Returns:

the Query object for proper chaining.

setRangeEnd

public Query setRangeEnd(ComplexKey endkey)

Stop returning records when the specified key is reached. The range key must be specified as a valid JSON string, but the ComplexKey class takes care of this. See the documentation of the ComplexKey class for more information on its usage.

Parameters:

endkey - The end of the key range.

Returns:

the Query object for proper chaining.

setBbox

public Query setBbox(double lowerLeftLong,
                     double lowerLeftLat,
                     double upperRightLong,
                     double upperRightLat)

Sets the params for a spatial bounding box view query.

Parameters:

lowerLeftLong - The longitude of the lower left corner.

lowerLeftLat - The latitude of the lower left corner.

upperRightLong - The longitude of the upper right corner.

upperRightLat - The latitude of the upper right corner.

Returns:

The bench.OldQuery instance.

willReduce

public boolean willReduce()

Read if reduce is enabled or not.

Returns:

Whether reduce is enabled or not.

willIncludeDocs

public boolean willIncludeDocs()

Read if full documents will be included on the query.

Returns:

Whether the full documents will be included or not.

getLimit

public int getLimit()

Returns the currently set limit.

Returns:

The current limit (or -1 if none is set).

toString

public java.lang.String toString()

Returns the Query as a HTTP-compatible query string.

Overrides:

toString in class java.lang.Object

Returns:

the stringified query.

getArgs

public java.util.Map<java.lang.String,java.lang.Object> getArgs()

Helper method which collects all currently set arguments. This method is most suitable for testing and debugging.

Returns:

a map containing all args and their values.

encode

protected java.lang.String encode(java.lang.String source)

Helper method to properly encode a string. This method can be overridden if a different encoding logic needs to be used.

Parameters:

source - source string.

Returns:

encoded target string.

quote

protected java.lang.String quote(java.lang.String source)

Helper method to properly quote the string if its a JSON string.

Parameters:

source - source string.

Returns:

maybe quoted target string.

copy

public Query copy()

Copy the current Query object into another one.

Returns:

an identical copy.