query
Returns a Flow which may be collected to execute a cluster-level SQL++ 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
the SQL++ statement to execute.
options common to all requests.
parameters to the SQL++ statement.
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.
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.
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.
pass true if the SQL++ statement does not modify documents. This allows the client to retry the query if necessary.
pass false if this is a commonly used query that should be turned into a prepared statement for faster execution.
pass true to use a full-text index instead of a query index.
pass true to include metrics in the response (access via QueryMetadata.metrics). Relatively inexpensive, and may be enabled in production with minimal impact.
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.
Specifies the maximum parallelism for the query.
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.
Controls the number of items execution operators can batch for Fetch from the KV.
Maximum number of items each execution operator can buffer between various operators.
an arbitrary string that identifies this query for diagnostic purposes.
an "escape hatch" for passing arbitrary query options that aren't otherwise exposed by this method.
may use replicas if primary is down If true, the server is allowed to use data from replicas (which may be stale) when executing the query. If false, the server must use up-to-date data from primaries. If null (the default), honor the server-side configuration for this setting.