Query

Query

A Couchbase Lite View Query.

Syntax


@interface CBLQuery : NSObject
class CBLQuery : NSObject
public class Query
public class Query
public class Query

Summary


Enums
Specifies the possible behaviors of an all-documents Query. Note that these are not flags; you can't combine more than one.
Used to specify when a View index is updated when running a Query.
Properties
AllDocsMode
allDocsMode { get; set; }
Possible modes of an all-docs query. See the AllDocsMode enumeration for details.
Database
database { get; }
Gets the Database that owns the Query's View.
boolean
descending { get; set; }
Gets or sets whether the rows be returned in descending key order. Default value is false.
Object
endKey { get; set; }
Gets or sets the last key to return. If null, the enumeration will continue to the end of the index. (Note that if the query is descending, the endKey will be the lowest key to return, and a null value means to stop at the lowest key of the index.)
String
endKeyDocId { get; set; }
Gets or sets the Document id of the last value to return. A null value has no effect. This is useful if the view contains multiple identical keys, making endKey ambiguous.
int
groupLevel { get; set; }
Gets or sets whether results will be grouped in Views that have reduce functions.
boolean
inclusiveEnd { get; set; }
Specifies whether rows whose key is exactly equal to the endKey should be returned. (Defaults to true.)
boolean
inclusiveStart { get; set; }
Specifies whether rows whose key is exactly equal to the startKey should be returned. (Defaults to true.)
IndexUpdateMode
indexUpdateMode { get; set; }
Gets or sets when a View index is updated when running a Query.
Object[]
keys { get; set; }
Gets or sets the keys of the values to return. A null value has no effect.
int
limit { get; set; }
Gets or sets the maximum number of rows to return. The default value is 0, meaning 'unlimited'.
boolean
mapOnly { get; set; }
Gets or sets whether to only use the map function without using the reduce function.
Func<QueryRow, bool>
postFilter { get; set; }
An optional predicate (boolean-valued function) that filters the rows returned from the query: the postFilter is called on every row, and if it returns false, that row is skipped.
boolean
prefetch { get; set; }
Gets or sets whether to include the entire Document content with the results. The Documents can be accessed via the QueryRow's documentProperties property.
int
prefixMatchLevel { get; set; }
If nonzero, enables prefix matching of string or array keys. * A value of 1 treats the endKey itself as a prefix: if it's a string, keys in the index that come after the endKey, but begin with the same prefix, will be matched. (For example, if the endKey is 'foo' then the key 'foolish' in the index will be matched, but not 'fong'.) Or if the endKey is an array, any array beginning with those elements will be matched. (For example, if the endKey is [1], then [1, 'x'] will match, but not [2].) If the key is any other type, there is no effect. * A value of 2 assumes the endKey is an array and treats its final item as a prefix, using the rules above. (For example, an endKey of [1, 'x'] will match [1, 'xtc'] but not [1, 'y'].) * A value of 3 assumes the key is an array of arrays, etc. Note that if the 'descending' property is also set, the search order is reversed and the above discussion applies to the 'startKey', not the 'endKey'.
int
skip { get; set; }
Gets or sets the number of initial rows to skip. Default value is 0.
Object
startKey { get; set; }
Gets or sets the first key to return. If null, the enumeration will start at the first key in the index. (Note that if the query is descending, the startKey will be the highest key to return, and a null value means to start at the highest key of the index.)
String
startKeyDocId { get; set; }
Gets or sets the Document id of the first value to return. A null value has no effect. This is useful if the view contains multiple identical keys, making startKey ambiguous.
Methods
QueryEnumerator
run()
Runs the Query and returns an enumerator over the result rows.
void
Runs the Query asynchronously and calls the QueryCompleteDelegate on completion.
LiveQuery
Returns a new LiveQuery with identical properties to the the Query.
Delegates
void
A delegate that can be called to signal the completion of a Query.

Enums


AllDocsMode
Specifies the possible behaviors of an all-documents Query. Note that these are not flags; you can't combine more than one.

Values

AllDocs All non-deleted documents, ordered by ID (the default.)
IncludeDeleted Like AllDocs but includes deleted documents.
ShowConflicts Adds details about conflicting revisions, in documents with conflicts.
OnlyConflicts Only returns documents that are in conflict.
BySequence Orders the documents by sequence number, i.e. in the order in which they were last modified.

Syntax

typedef enum {
    kCBLAllDocs,
    kCBLIncludeDeleted,
    kCBLShowConflicts,
    kCBLOnlyConflicts,
    kCBLBySequence
} CBLAllDocsMode;
enum CBLAllDocsMode: Int {
    case AllDocs
    case IncludeDeleted
    case ShowConflicts
    case OnlyConflicts
    case BySequence
}
public enum AllDocsMode {
    ALL_DOCS,
    INCLUDE_DELETED,
    SHOW_CONFLICTS,
    ONLY_CONFLICTS,
    BY_SEQUENCE
}
public enum AllDocsMode {
    ALL_DOCS,
    INCLUDE_DELETED,
    SHOW_CONFLICTS,
    ONLY_CONFLICTS,
    BY_SEQUENCE
}
public enum AllDocsMode
{
    AllDocs,
    IncludeDeleted,
    ShowConflicts,
    OnlyConflicts,
    BySequence
}
IndexUpdateMode
Used to specify when a View index is updated when running a Query.

Values

Before If needed, update the index before running the Query (default). This guarantees up-to-date results at the expense of a potential delay in receiving results.
Never Never update the index when running a Query. This guarantees receiving results the fastest at the expense of potentially out-of-date results.
After If needed, update the index asynchronously after running the Query. This guarantees receiving results the fastest, at the expense of potentially out-of-date results, and that subsequent Queries will return more accurate results.

Syntax

typedef enum {
    kCBLUpdateIndexBefore,
    kCBLUpdateIndexNever,
    kCBLUpdateIndexAfter
} CBLIndexUpdateMode;
enum CBLIndexUpdateMode: Int {
    case kCBLUpdateIndexBefore
    case kCBLUpdateIndexNever
    case kCBLUpdateIndexAfter
}
public enum IndexUpdateMode {
    BEFORE,
    NEVER,
    AFTER
}
public enum IndexUpdateMode {
    BEFORE,
    NEVER,
    AFTER
}
public enum QueryIndexUpdateMode {
    Before,
    Never,
    After
}

Properties


AllDocsMode allDocsMode { get; set; }
Possible modes of an all-docs query. See the AllDocsMode enumeration for details.

Syntax

@property (readwrite) CBLAllDocsMode allDocsMode
var allDocsMode: CBLAllDocsMode
public AllDocsMode getAllDocsMode()
public void setAllDocsMode(AllDocsMode allDocsMode)
public AllDocsMode getAllDocsMode()
public void setAllDocsMode(AllDocsMode allDocsMode)
public AllDocsMode AllDocsMode { get; set; }
Database database { get; }
Gets the Database that owns the Query's View.

Syntax

@property (readonly) CBLDatabase * database
var database: CBLDatabase { get }
public Database getDatabase()
public Database getDatabase()
public Database Database { get; }
boolean descending { get; set; }
Gets or sets whether the rows be returned in descending key order. Default value is false.

Syntax

@property (readwrite) BOOL descending
var descending: Bool
public int isDescending()
public void setDescending(boolean descending)
public int isDescending()
public void setDescending(boolean descending)
public Boolean Descending { get; set; }
Object endKey { get; set; }
Gets or sets the last key to return. If null, the enumeration will continue to the end of the index. (Note that if the query is descending, the endKey will be the lowest key to return, and a null value means to stop at the lowest key of the index.)

Syntax

@property (readwrite) id endKey
var endKey: AnyObject!
public Object getEndKey()
public void setEndKey(Object endKey)
public Object getEndKey()
public void setEndKey(Object endKey)
public Object EndKey { get; set; }
String endKeyDocId { get; set; }
Gets or sets the Document id of the last value to return. A null value has no effect. This is useful if the view contains multiple identical keys, making endKey ambiguous.

Syntax

@property (readwrite) NSString * endKeyDocID
var endKeyDocID: String!
public String getEndKeyDocId()
public void setEndKeyDocId(String endKeyDocId)
public String getEndKeyDocId()
public void setEndKeyDocId(String endKeyDocId)
public String EndKeyDocId { get; set; }
int groupLevel { get; set; }
Gets or sets whether results will be grouped in Views that have reduce functions.

Syntax

@property (readwrite) NSUInteger groupLevel
var groupLevel: UInt
public int getGroupLevel()
public void setGroupLevel(int groupLevel)
public int getGroupLevel()
public void setGroupLevel(int groupLevel)
public int GroupLevel { get; set; }
boolean inclusiveEnd { get; set; }
Specifies whether rows whose key is exactly equal to the endKey should be returned. (Defaults to true.)

Syntax

@property BOOL inclusiveEnd
var inclusiveEnd: Bool
public int isInclusiveEnd()
public void setInclusiveEnd(boolean inclusiveEnd)
public int isInclusiveEnd()
public void setInclusiveEnd(boolean inclusiveEnd)
public Boolean InclusiveEnd { get; set; }
boolean inclusiveStart { get; set; }
Specifies whether rows whose key is exactly equal to the startKey should be returned. (Defaults to true.)

Syntax

@property BOOL inclusiveStart
var inclusiveStart: Bool
public int isInclusiveStart()
public void setInclusiveStart(boolean inclusiveStart)
public int isInclusiveStart()
public void setInclusiveStart(boolean inclusiveStart)
public Boolean InclusiveStart { get; set; }
IndexUpdateMode indexUpdateMode { get; set; }
Gets or sets when a View index is updated when running a Query.

Syntax

@property (readwrite) CBLIndexUpdateMode indexUpdateMode
var indexUpdateMode: CBLIndexUpdateMode
public IndexUpdateMode getIndexUpdateMode()
public void setIndexUpdateMode(IndexUpdateMode indexUpdateMode)
public IndexUpdateMode getIndexUpdateMode()
public void setIndexUpdateMode(IndexUpdateMode indexUpdateMode)
public IndexUpdateMode IndexUpdateMode { get; set; }
Object[] keys { get; set; }
Gets or sets the keys of the values to return. A null value has no effect.

Syntax

@property (readwrite) NSArray * keys
var keys: [AnyObject]!
public List<Object> getKeys()
public void setKeys(List<Object> keys)
public List<Object> getKeys()
public void setKeys(List<Object> keys)
public IEnumerable<Object> Keys { get; set; }
int limit { get; set; }
Gets or sets the maximum number of rows to return. The default value is 0, meaning 'unlimited'.

Syntax

@property (readwrite) NSUInteger limit
var limit: UInt
public int getLimit()
public void setLimit(int limit)
public int getLimit()
public void setLimit(int limit)
public int Limit { get; set; }
boolean mapOnly { get; set; }
Gets or sets whether to only use the map function without using the reduce function.

Syntax

@property (readwrite) BOOL mapOnly
var mapOnly: Bool
public boolean isMapOnly()
public void setMapOnly(boolean mapOnly)
public boolean isMapOnly()
public void setMapOnly(boolean mapOnly)
public Boolean MapOnly { get; set; }
Func<QueryRow, bool> postFilter { get; set; }
An optional predicate (boolean-valued function) that filters the rows returned from the query: the postFilter is called on every row, and if it returns false, that row is skipped.

Syntax

@property NSPredicate* postFilter
var postFilter: NSPredicate?
public Predicate<QueryRow> getPostFilter()
public void setPostFilter(Predicate<QueryRow> postFilter)
public Predicate<QueryRow> getPostFilter()
public void setPostFilter(Predicate<QueryRow> postFilter)
public Func<QueryRow, bool> postFilter { get; set; }
boolean prefetch { get; set; }
Gets or sets whether to include the entire Document content with the results. The Documents can be accessed via the QueryRow's documentProperties property.

Syntax

@property (readwrite) BOOL prefetch
var prefetch: Bool
public boolean shouldPrefetch()
public void setPrefetch(boolean prefetch)
public boolean shouldPrefetch()
public void setPrefetch(boolean prefetch)
public Boolean Prefetch { get; set; }
int prefixMatchLevel { get; set; }
If nonzero, enables prefix matching of string or array keys. * A value of 1 treats the endKey itself as a prefix: if it's a string, keys in the index that come after the endKey, but begin with the same prefix, will be matched. (For example, if the endKey is 'foo' then the key 'foolish' in the index will be matched, but not 'fong'.) Or if the endKey is an array, any array beginning with those elements will be matched. (For example, if the endKey is [1], then [1, 'x'] will match, but not [2].) If the key is any other type, there is no effect. * A value of 2 assumes the endKey is an array and treats its final item as a prefix, using the rules above. (For example, an endKey of [1, 'x'] will match [1, 'xtc'] but not [1, 'y'].) * A value of 3 assumes the key is an array of arrays, etc. Note that if the 'descending' property is also set, the search order is reversed and the above discussion applies to the 'startKey', not the 'endKey'.

Syntax

@property NSUInteger prefixMatchLevel
var prefixMatchLevel: UInt
public int getPrefixMatchLevel()
public void setPrefixMatchLevel(int prefixMatchLevel)
public int getPrefixMatchLevel()
public void setPrefixMatchLevel(int prefixMatchLevel)
Not applicable.
int skip { get; set; }
Gets or sets the number of initial rows to skip. Default value is 0.

Syntax

@property (readwrite) NSUInteger skip
var skip: UInt
public int getSkip()
public void setSkip(int skip)
public int getSkip()
public void setSkip(int skip)
public int Skip { get; set; }
Object startKey { get; set; }
Gets or sets the first key to return. If null, the enumeration will start at the first key in the index. (Note that if the query is descending, the startKey will be the highest key to return, and a null value means to start at the highest key of the index.)

Syntax

@property (readwrite) id startKey
var startKey: AnyObject!;
public Object getStartKey()
public void setStartKey(Object startKey)
public Object getStartKey()
public void setStartKey(Object startKey)
public Object StartKey { get; set; }
String startKeyDocId { get; set; }
Gets or sets the Document id of the first value to return. A null value has no effect. This is useful if the view contains multiple identical keys, making startKey ambiguous.

Syntax

@property (readwrite) NSString * startKeyDocID
var startKeyDocID: String!
public String getStartKeyDocId()
public void setStartKeyDocId(String startKeyDocId)
public String getStartKeyDocId()
public void setStartKeyDocId(String startKeyDocId)
public String StartKeyDocId { get; set; }

Methods


Runs the Query and returns an enumerator over the result rows.

Errors

Returns an error if an issue occurs while executing the Query.

Syntax

-(CBLQueryEnumerator *)run:(NSError **)outError
func run(outError: NSErrorPointer) -> CBLQueryEnumerator!
public QueryEnumerator run() throws CouchbaseLiteException
public QueryEnumerator run() throws CouchbaseLiteException
public QueryEnumerator Run()
void runAsync( QueryCompleteDelegate onComplete)
Runs the Query asynchronously and calls the QueryCompleteDelegate on completion.

Parameters

delegate The delegate to run asynchronously.

Syntax

-(void)runAsync:(void (^)(CBLQueryEnumerator *, NSError *))onComplete
func runAsync(onComplete: (CBLQueryEnumerator!, NSError!) -> Void)!
public Future runAsync(QueryCompleteListener queryCompleteListener)
public Future runAsync(QueryCompleteListener queryCompleteListener)
public void RunAsync(QueryCompleteDelegate onComplete)
LiveQuery toLiveQuery()
Returns a new LiveQuery with identical properties to the the Query.

Returns

A new LiveQuery with identical properties to the the Query.

Syntax

-(CBLLiveQuery *)asLiveQuery
func asLiveQuery() -> CBLLiveQuery!
public LiveQuery toLiveQuery()
public LiveQuery toLiveQuery()
public LiveQuery ToLiveQuery()

Delegates


void QueryCompleteDelegate( QueryEnumerator rows, Error error)
A delegate that can be called to signal the completion of a Query.

Parameters

rows The result rows from the Query.
error The error, if any, that occured during the execution of the Query

Syntax

^(CBLQueryEnumerator * rows, NSError * error) {
    ...
}
{ (CBLQueryEnumerator!, NSError!) -> Void in
}
public interface QueryCompleteListener {
    void completed(QueryEnumerator rows, Throwable error);
}
public interface QueryCompleteListener {
    void completed(QueryEnumerator rows, Throwable error);
}
public delegate void QueryCompleteDelegate(QueryEnumerator rows, Exception error);