CBC-N1QLBACK(1)

🌸 CBC-N1QLBACK — the bestie edition

okay so bestie, you know how we stan a stress test? this one is literally from the General Commands Manual section, and it's here to put your Couchbase Query (N1QL) cluster through its cardio. let's go 💖

---

✨ NAME

cbc-n1qlback — a whole Stress Test for Couchbase Query (N1QL) 🔥

---

🎀 SYNOPSIS

cbc-n1qlback -f QUERYFILE [OPTIONS]

---

💅 DESCRIPTION

so cbc-n1qlback spawns a bunch of threads, and every single thread runs a set of your queries. like, you bring the queries, it brings the chaos ✨

heads up: you must pass it the path to a file that has the queries you wanna run — one per line. and each query has to be in the format of the actual HTTP POST body (JSON format) that gets sent to the server. so for the simple girlies, you only need to set the statement field:

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

for the more complex queries (think placeholders, custom options, main character stuff), you can go check the N1QL REST API reference. iykyk 🫶

okay for example, this line right here shows you how to use a named parameter:

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

there's also a special query option called "n1qlback", and it gets stripped before the payload is sent. right now it lets you say whether that particular query must be prepared before execution:

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

and ngl, n1qlback requires that any resources (data items, indexes) are already defined. it does not set them up for you, bestie. it is not your mom 💀

---

👑 OPTIONS

workload generation girlies 💪

• -f, --queryfile=PATH — path to the file containing the query bodies to execute, in JSON format, one query per line. see above for the format, bestie.
• -t, --num-threads=NTHREADS — sets the number of threads (and therefore the number of client instances) running concurrently. every thread gets its own client object, no sharing, no drama 🎀

how it connects to the cluster 🌐

@@common-options.markdown@@

• -e, --error-log=PATH — path to a file where the command writes failed queries along with the error details. use this when you're like "why is the ERRORS metric not zero 😭" — this is the answer.

---

🦋 ADDITIONAL OPTIONS

these ones can be tucked into the connection string (through the -U option) as URI-style query params, like:

couchbase://host/bucket?option1=value1&option2=value2

or you can pass them as individual key=value pairs to the -D switch, like:

-Doption1=value1 -Doption2=value

the -D thing internally builds the connection string, and honestly it's just there as a convenience so options are easy to yeet onto the command line ✨

@@common-additional-options.markdown@@

---

🌈 EXAMPLES

okay so this one creates 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)'

then make a text file queries.txt with the following content (and note that the fourth query has a 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}}

now run the test load:

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

slay. that's it. that's the test. 🦋

---

💀 BUGS

the options of this command are subject to change. so like, don't get too attached 💅

---

⭐ SEE ALSO

• cbc(1)
• cbc-pillowfight(1)
• cbcrc(4)

---

🧚 HISTORY

the cbc-n1qlback tool first showed up in libcouchbase 2.4.10. a legend was born ✨

---

that's a wrap, bestie! this page is from the CBC-N1QLBACK(1) manual, dated July 2024. 💖 go forth and stress test responsibly, mwah 🫶