kotlin-client/com.couchbase.client.kotlin/Cluster/query

query

fun query(statement: String, common: CommonOptions = CommonOptions.Default, parameters: QueryParameters = QueryParameters.None, @SinceCouchbase(value = "7.1") preserveExpiry: Boolean = false, serializer: JsonSerializer? = null, consistency: QueryScanConsistency = QueryScanConsistency.notBounded(), readonly: Boolean = false, adhoc: Boolean = true, flexIndex: Boolean = false, metrics: Boolean = false, profile: QueryProfile = QueryProfile.OFF, maxParallelism: Int? = null, scanCap: Int? = null, pipelineBatch: Int? = null, pipelineCap: Int? = null, clientContextId: String? = UUID.randomUUID().toString(), raw: Map<String, Any?> = emptyMap()): Flow<QueryFlowItem>

Returns a Flow which may be collected to execute a cluster-level N1QL query and process the results.

The returned Flow is cold, meaning the query is not executed unless the Flow is collected. If you collect the flow multiple times, the query is executed each time.

The extension function Flow<QueryFlowItem>.execute() may be used when the results are known to fit in memory. It simply collects the flow into a QueryResult.

For larger query results, prefer the streaming version which takes a lambda to invoke when each row is received from the server: Flow<QueryFlowItem>.execute { row -> ... }.

Samples

import com.couchbase.client.kotlin.Cluster
import com.couchbase.client.kotlin.query.QueryMetadata
import com.couchbase.client.kotlin.query.QueryResult
import com.couchbase.client.kotlin.query.execute
fun main() { 
   //sampleStart 
   // Buffered query, for when results are known to fit in memory
val result: QueryResult = cluster
    .query("select * from `travel-sample` limit 10")
    .execute()
result.rows.forEach { println(it) }
println(result.metadata) 
   //sampleEnd
}

import com.couchbase.client.kotlin.Cluster
import com.couchbase.client.kotlin.query.QueryMetadata
import com.couchbase.client.kotlin.query.QueryResult
import com.couchbase.client.kotlin.query.execute
fun main() { 
   //sampleStart 
   // Streaming query, for when result size is large or unbounded
val metadata: QueryMetadata = cluster
    .query("select * from `travel-sample`")
    .execute { row -> println(row) }
println(metadata) 
   //sampleEnd
}

import com.couchbase.client.kotlin.Cluster
import com.couchbase.client.kotlin.query.QueryMetadata
import com.couchbase.client.kotlin.query.QueryResult
import com.couchbase.client.kotlin.query.execute
fun main() { 
   //sampleStart 
   // Single-value query with anonymous result
val count = cluster
    .query("select count(*) from `travel-sample`")
    .execute()
    .valueAs<Long>() // uses default name "$1" 
   //sampleEnd
}

import com.couchbase.client.kotlin.Cluster
import com.couchbase.client.kotlin.query.QueryMetadata
import com.couchbase.client.kotlin.query.QueryResult
import com.couchbase.client.kotlin.query.execute
fun main() { 
   //sampleStart 
   // Single-value query with named result
val count = cluster
    .query("select count(*) as count from `travel-sample`")
    .execute()
    .valueAs<Long>("count") 
   //sampleEnd
}

Parameters

statement

the N1QL statement to execute.

common

options common to all requests.

parameters

parameters to the N1QL statement.

preserveExpiry

pass true if you want the query engine to preserve existing expiration times for any documents modified by this query. Requires Couchbase Server 7.1 or later.

serializer

the serializer to use for converting parameters to JSON, and the default serializer for parsing QueryRow content. Defaults to the serializer configured on the cluster environment.

consistency

required if you want to read your own writes. Values other than QueryScanConsistency.notBounded tell the server to wait for the indexer to catch up with a certain state of the K/V service before executing the query.

readonly

pass true if the N1QL statement does not modify documents. This allows the client to retry the query if necessary.

adhoc

pass false if this is a commonly used query that should be turned into a prepared statement for faster execution.

flexIndex

pass true to use a full-text index instead of a query index.

metrics

pass true to include metrics in the response (access via QueryMetadata.metrics). Relatively inexpensive, and may be enabled in production with minimal impact.

profile

specifies how much profiling information to include in the response (access via QueryMetadata.profile). Profiling is relatively expensive, and can impact the performance of the server query engine. Not recommended for use in production, unless you're diagnosing a specific issue. Note this is an Enterprise Edition feature. On Community Edition the parameter will be accepted, but no profiling information returned.

maxParallelism

Specifies the maximum parallelism for the query.

scanCap

Maximum buffered channel size between the indexer client and the query service for index scans. This parameter controls when to use scan backfill. Use 0 or a negative number to disable. Smaller values reduce GC, while larger values reduce indexer backfill.

pipelineBatch

Controls the number of items execution operators can batch for Fetch from the KV.

pipelineCap

Maximum number of items each execution operator can buffer between various operators.

clientContextId

an arbitrary string that identifies this query for diagnostic purposes.

raw

an "escape hatch" for passing arbitrary query options that aren't otherwise exposed by this method.