SYNOPSIS

cbc-n1qlback -f QUERYFILE [OPTIONS]

DESCRIPTION

cbc-n1qlback creates a specified number of threads each executing a set of user defined queries.

cbc-n1qlback requires that it be passed the path to a file containing the queries to execute; one per line. The query should be in the format of the actual HTTP POST body (in JSON format) to be sent to the server. For simple queries, only the statement field needs to be set:

{"statement":"SELECT country FROM `travel-sample`"}
{"statement":"SELECT country, COUNT(country) FROM `travel-sample` GROUP BY country"}

For more complex queries (for example, placeholders, custom options), you may refer to the N1QL REST API reference.

For example, the following line shows how to use named parameter

{"statement":"SELECT RAW meta().id FROM `travel-sample` WHERE type=$type LIMIT 1", "$type":"airline"}

There is also special query option, "n1qlback", which is stripped before sending the payload. Currently it allows to tell if the particular query must be prepared before execution:

{"statement":"SELECT * FROM `travel-sample` WHERE type=$type LIMIT 10", "$type":"airline", "n1qlback": {"prepare": true}}

n1qlback requires that any resources (data items, indexes) are already defined.

OPTIONS

The following options control workload generation:

-f --queryfile=_PATH_: Path to a file containing the query bodies to execute in JSON format, one query per line. See above for the format.
-t, --num-threads=_NTHREADS_: Set the number of threads (and thus the number of client instances) to run concurrently. Each thread is assigned its own client object.

The following options control how cbc-n1qlback connects to the cluster

@common-options.markdown@

-e, --error-log=_PATH_: Path to a file, where the command will write failed queries along with error details. Use this option to figure out why ERRORS metric is not zero.

ADDITIONAL OPTIONS

The following options may be included in the connection string (via the -U option) as URI-style query params (e.g. couchbase://host/bucket?option1=value1&option2=value2) or as individual key=value pairs passed to the -D switch (e.g. -Doption1=value1 -Doption2=value). The -D will internally build the connection string, and is provided as a convenience for options to be easily passed on the command-line

@common-additional-options.markdown@

EXAMPLES

The following will create a file with 3 queries and 5 threads alternating between them. It also creates indexes on the travel-sample bucket

cbc n1ql 'CREATE INDEX ix_name ON `travel-sample`(name)'
cbc n1ql 'CREATE INDEX ix_country ON `travel-sample`(country)'

Crete text file queries.txt with the following content (note that fourth query has parameter)

{"statement":"SELECT country FROM `travel-sample` WHERE `travel-sample`.country = \"United States\""}
{"statement":"SELECT name FROM `travel-sample` LIMIT 10"}
{"statement":"SELECT country, COUNT(country) FROM `travel-sample` GROUP BY country"}
{"statement":"SELECT RAW meta().id FROM `travel-sample` WHERE type=$type LIMIT 1", "$type":"airline", "n1qlback": {"prepare": true}}

Run the test load

cbc-n1qlback --num-threads 5 --queryfile queries.txt

BUGS

This command's options are subject to change.

HISTORY

The cbc-n1qlback tool was first introduced in libcouchbase 2.4.10