NoSQLBench

https://docs.nosqlbench.io
Admin
NoSQLBench is a comprehensive systems testing tool for benchmarking and load testing NoSQL databases...
Tokens:163,958
Snippets:1,507
Trust Score:6.8
Update:8 months ago
Show doc for...
Tokens:
Raw
### Run NoSQLBench with Advanced Options

Source: https://docs.nosqlbench.io/getting-started/00-get-nosqlbench

Demonstrates a detailed NoSQLBench command execution with multiple parameters: specifying workload, scenario, output filename, format, cycle count, rate, and progress reporting.

```bash
1| ./nb5 examples/bindings-basics default \
  
---|---  
2|  filename=exampledata.out \
  
3|  format=csv \
  
4|  cycles=10000 \
  
5|  rate=100 \
  
6|  --progress console:1s
```

--------------------------------

### Run DSE in Docker

Source: https://docs.nosqlbench.io/getting-started/01-test-target

Starts a DataStax Enterprise (DSE) server instance using Docker. This command pulls the specified DSE image and runs it in detached mode, exposing the CQL port (9042). Ensure Docker is installed and running.

```docker
docker run -e DS_LICENSE=accept --name my-dse -p 9042:9042 -d datastax/dse-server:6.8.17-ubi7
```

--------------------------------

### Run a Simple Built-in Workload

Source: https://docs.nosqlbench.io/getting-started

Executes a basic NoSQLBench workload using a built-in scenario named 'bindings-basics'. This command assumes the nb5 binary is in the current directory or in the system's PATH.

```bash
./nb5 examples/bindings-basics
```

--------------------------------

### Download and Execute Latest nb5 Binary (Linux)

Source: https://docs.nosqlbench.io/getting-started

Downloads the latest nb5 Linux binary using curl, makes it executable with chmod, and verifies the installation by printing the version. This is the recommended method for Linux users.

```bash
# download the latest nb5 binary and make it executable
curl -L -O https://github.com/nosqlbench/nosqlbench/releases/latest/download/nb5
chmod +x nb5
./nb5 --version
```

--------------------------------

### Advanced NoSQLBench Command with Options

Source: https://docs.nosqlbench.io/getting-started

Demonstrates a detailed NoSQLBench command with multiple options to customize workload execution. It specifies the workload, scenario, output filename, format, cycle count, rate, and progress reporting.

```bash
1| ./nb5 examples/bindings-basics default \
2|  filename=exampledata.out \
3|  format=csv \
4|  cycles=10000 \
5|  rate=100 \
6|  --progress console:1s
```

--------------------------------

### Run Workload with Docker Metrics Dashboard

Source: https://docs.nosqlbench.io/getting-started

Executes a NoSQLBench workload and enables a live metrics dashboard using the `--docker-metrics` option. This requires Docker to be installed and the user to have permissions to use it.

```bash
./nb5 examples/bindings-basics default \
 filename=exampledata.out \
 format=csv \
 cycles=10000 \
 rate=100 \
 --progress console:1s \
 --docker-metrics
```

--------------------------------

### Execute a Command with Arguments (CLI)

Source: https://docs.nosqlbench.io/user-guide

This example demonstrates executing the 'start' command with named arguments 'driver' and 'alias'. Commands are single words without dashes, and named arguments follow the command in 'name=value' format.

```bash
nb5 start driver=diag alias=example
```

--------------------------------

### Start an Activity Asynchronously

Source: https://docs.nosqlbench.io/user-guide/cli-scripting

The `start` command initiates an activity without blocking the scenario script. It runs asynchronously, allowing multiple activities to start concurrently. Requires a driver and optionally an alias for later interaction.

```bash
start driver=<driver> alias=<alias> ...
```

--------------------------------

### CQLd4 Op Template Examples

Source: https://docs.nosqlbench.io/reference/drivers/cqld4

Demonstrates various statement forms for the CQLd4 driver in NoSQLBench. Includes examples for prepared, simple, raw, gremlin, and fluent statements, showcasing their syntax and intended use cases.

```yaml
ops:

  # prepared statement
  # allows for parameterization via bindings, and uses prepared statements internally
  example-prepared-cql-stmt:
    prepared: |
     select one, two from buckle.myshoe where ...

  # prepared statement (verbose form)
  example-prepared-cql-stmt-verbose:
    type: prepared
    stmt: |
      select one, two from buckle.myshoe where ...

  # simple statement
  # allows for parameterization via bindings, but does not use prepared statements internally
  example-simple-cql-stmt:
    simple: |
     select three, four from knock.onthedoor where ...

  # raw statement
  # pre-renders the statement into a string, with no driver-supervised parameterization
  # useful for testing variant DDL where some fields are not parameterizable
  # NOTE: the raw form does its best to quote non-literals where needed, but you may
  # have to inject single or double quotes in special cases.
  example-raw-cql-stmt:
    raw: |
     create table if not exist {ksname}.{tblname} ...

  # gremlin statement using the fluent API, as it would be written in a client application
  example-fluent-graph-stmt:
    fluent: >-
      g.V().hasLabel("device").has("deviceid", UUID.fromString({deviceid}))
    # if imports are not specified, the following is auto imported.
    # if imports are specified, you must also provide the __ class if needed
    imports:
     - org.apache.tinkerpop.gremlin.process.traversal.dsl.graph.__

  # gremlin statement using string API (not recommended)
  example-raw-gremlin-stmt:
    gremlin: >-
      g.V().hasLabel("device").has("deviceid", UUID.fromString('{deviceid}')

```

--------------------------------

### Download Latest nb5 JAR

Source: https://docs.nosqlbench.io/getting-started

Downloads the latest nb5 JAR file using curl and verifies the download by printing the version using `java -jar nb5.jar --version`. This method is suitable for systems where the Linux binary is not preferred or available.

```bash
# download the latest nb5 jar
curl -L -O https://github.com/nosqlbench/nosqlbench/releases/latest/download/nb5.jar
java -jar nb5.jar --version
```

--------------------------------

### Run a Specific Scenario within a Workload

Source: https://docs.nosqlbench.io/getting-started

Executes a specific scenario named 'default' from the 'bindings-basics' workload template. This command explicitly specifies both the workload template and the scenario name.

```bash
./nb5 examples/bindings-basics default
```

--------------------------------

### Configure NoSQLBench for AstraDB Connection

Source: https://docs.nosqlbench.io/getting-started/01-test-target

Provides configuration patterns for NoSQLBench to connect to DataStax AstraDB. It demonstrates using driver settings and referencing secure connect bundles and user/password files for credential management. This is useful for keeping sensitive information out of logs.

```properties
... driver=cqld4 scb=<secureconnectbundle> userfile=<userfile> passfile=<passfile> ...
```

```properties
... driver=cqld4 scb=creds1/scb-somename.zip userfile=creds1/userfile passfile=creds1/passfile ...
```

--------------------------------

### Run stdout Activity

Source: https://docs.nosqlbench.io/reference/drivers/stdout

This example demonstrates how to run a basic stdout activity named 'stdout-test'. It utilizes the 'driver=stdout' and 'workload=stdout-test' parameters to initiate the activity.

```bash
nb5 driver=stdout workload=stdout-test

```

--------------------------------

### Run Activity to Completion

Source: https://docs.nosqlbench.io/user-guide/cli-scripting

The `run` command executes an activity and waits for its completion before proceeding with the scenario script. It's equivalent to starting an activity and then awaiting its completion.

```bash
run driver=<driver> alias=<alias> ...
```

--------------------------------

### Simple Op Template Example

Source: https://docs.nosqlbench.io/user-guide/op-templates

A basic example of an op template using a simple string format. It demonstrates how to define an operation with a dynamic component using a placeholder.

```yaml
op: "example {{Combinations('a-z')}} body"
```

--------------------------------

### Enable Docker Metrics Infrastructure

Source: https://docs.nosqlbench.io/user-guide/cli-options

Enlist NoSQLBench to stand up your metrics infrastructure using a local Docker runtime. This automatically starts and configures Graphite, Prometheus, and Grafana.

```bash
--docker-metrics
```

--------------------------------

### SpecTest Formatting Example - YAML, JSON, Ops

Source: https://docs.nosqlbench.io/reference/workload_definition/01-spectest-formatting

Demonstrates the required sequence and format markers for SpecTest examples. This includes a YAML workload, its JSON representation, and an Ops section, all enclosed in fenced code blocks with specific prefixes.

```markdown
_format:_
Copy```yaml
# some yaml here

```

_json:_
Copy```json
[]

```

_ops:_
Copy```json
[]

```
```

--------------------------------

### Multi-Document YAML Workload Example

Source: https://docs.nosqlbench.io/workloads-101/08-multi-docs

This example demonstrates how to define two distinct YAML documents within a single file, separated by '---'. Each document has its own bindings and statements, allowing for parameterized and tagged operations to be organized separately. The output shows how NoSQLBench processes these documents.

```yaml
# stdout-test.yaml
bindings:
 docval: WeightedStrings('doc1.1:1;doc1.2:2;')
statements:
 - "doc1.form1 {docval}\n"
 - "doc1.form2 {docval}\n"
---
bindings:
 numname: NumberNameToString()
statements:
 - "doc2.number {numname}\n"
```

```bash
[test]$ ./nb5 run driver=stdout workload=stdout-test cycles=10
```

--------------------------------

### NB S4J Driver Configuration File Example

Source: https://docs.nosqlbench.io/reference/drivers/s4j

This is an example of a NoSQLBench S4J driver configuration file. It includes settings for the S4J API, Pulsar client, producers, and consumers. The comments provide links to relevant documentation for each section.

```properties
###########
# Overview: Starlight for JMS (S4J) API configuration items are listed at:
#           https://docs.datastax.com/en/fast-pulsar-jms/docs/1.1/pulsar-jms-reference.html#_configuration_options
enableTransaction=true

####
# S4J API specific configurations (non Pulsar specific) - jms.***

jms.enableClientSideEmulation=true
jms.usePulsarAdmin=false
#...

#####
# Pulsar client related configurations - client.***
# - Valid settings: http://pulsar.apache.org/docs/en/client-libraries-java/#client
#
# - These Pulsar client settings (without the "client." prefix) will be
#   directly used as S4J configuration settings, on a 1-to-1 basis.
#--------------------------------------
# only relevant when authentication is enabled
client.authPlugin=org.apache.pulsar.client.impl.auth.AuthenticationToken
client.authParams=file:///path/to/authentication/jwt/file
# only relevant when in-transit encryption is enabled
client.tlsTrustCertsFilePath=/path/to/certificate/file
#...

#####
# Producer related configurations (global) - producer.***
# - Valid settings: http://pulsar.apache.org/docs/en/client-libraries-java/#configure-producer
#
# - These Pulsar producer settings (without "producer." prefix) will be collectively (as a map)
#   mapped to S4J connection setting of "producerConfig"
#--------------------------------------
producer.blockIfQueueFull=true
# disable producer batching
#producer.batchingEnabled=false
#...

#####
# Consumer related configurations (global) - consumer.***
# - Valid settings: http://pulsar.apache.org/docs/en/client-libraries-java/#configure-consumer
#

```

--------------------------------

### Run MongoDB Activity with YAML Definition

Source: https://docs.nosqlbench.io/reference/drivers/mongodb

This example demonstrates how to execute a MongoDB activity using NoSQLBench, specifying the driver and a YAML file for activity definitions. It requires the `mongodb` driver and a valid YAML file path.

```bash
nb5 driver=mongodb yaml=activities/mongo-basic.yaml

```

--------------------------------

### Define Multiple Named Scenario Steps (YAML)

Source: https://docs.nosqlbench.io/reference/workload_definition/02-workload-structure

This YAML example illustrates defining a scenario named 'default' with multiple, sequentially named steps ('step1', 'step2'). Each step executes a command with specific aliases and parameters.

```yaml
scenarios:
  default:
    step1: run alias=first driver=diag cycles=10
    step2: run alias=second driver=diag cycles=10

```

--------------------------------

### NoSQLBench Workload Progress Output

Source: https://docs.nosqlbench.io/getting-started/02-scenarios

Example output from NoSQLBench during a workload run, showing the progress of the 'cql-keyvalue' workload. It displays the number of remaining, active, and completed operations, along with the percentage completion.

```text
Configured scenario log at ...
cql-keyvalue (remaining,active,completed)=(47168,1,2832) 006%
cql-keyvalue (remaining,active,completed)=(42059,2,7941) 016%
cql-keyvalue (remaining,active,completed)=(37107,2,12895) 026%
cql-keyvalue (remaining,active,completed)=(32060,1,17941) 036%
cql-keyvalue (remaining,active,completed)=(27060,2,22940) 046%
cql-keyvalue (remaining,active,completed)=(22058,2,27943) 056%
cql-keyvalue (remaining,active,completed)=(17058,1,32942) 066%
cql-keyvalue (remaining,active,completed)=(12059,2,37942) 076%
cql-keyvalue (remaining,active,completed)=(7059,1,42942) 086%
cql-keyvalue (remaining,active,completed)=(2060,1,47941) 096%
cql-keyvalue (remaining,active,completed)=(0,0,50000) 100% (last report)
```

--------------------------------

### Statement Forms and Examples

Source: https://docs.nosqlbench.io/reference/drivers

Explains the syntax for specifying statement types (`execute`, `query`, `update`) and provides examples of operation templates.

```APIDOC
## Statement Forms and Examples

### Description
Details the simplified syntax for specifying statement types and provides examples of operation templates for DDL and DML operations.

### Statement Forms

- **Simplified Syntax**: Uses a single `type` field with values `execute`, `query`, or `update`, and specifies the raw statements in the `stmt` field.
- **Direct Syntax**: Alternatively, one can directly use one of the types (`execute`, `query`, `update`) and provide the raw query directly.

### Op Template Examples

#### `drop-database`
- **Type**: `execute`
- **Statement**: `DROP DATABASE IF EXISTS TEMPLATE(database,baselines);`

#### `create-table`
- **Type**: `execute`
- **Statement**: `CREATE TABLE IF NOT EXISTS TEMPLATE(database,baselines).TEMPLATE(table,keyvalue);`

#### `select-table`
- **Type**: `query`
- **Statement**: `SELECT one, two, three FROM TEMPLATE(database,baselines).TEMPLATE(table,keyvalue) WHERE ...;`

#### `insert-table`
- **Type**: `update`
- **Statement**: `UPDATE TABLE TEMPLATE(database,baselines).TEMPLATE(table,keyvalue) SET key = 'value' WHERE ...;`

### Request Example (YAML Snippet)
```yaml
ops:
  drop-database:
    type: execute
    stmt: |
      DROP DATABASE IF EXISTS TEMPLATE(database,baselines);
  create-table:
    execute: |
      CREATE TABLE IF NOT EXISTS TEMPLATE(database,baselines).TEMPLATE(table,keyvalue);
  select-table:
    query: |
      SELECT one, two, three FROM TEMPLATE(database,baselines).TEMPLATE(table,keyvalue) WHERE ...;
  insert-table:
    update: |
      UPDATE TABLE TEMPLATE(database,baselines).TEMPLATE(table,keyvalue) SET key = 'value' WHERE ...;
```

### Response
N/A (These are configuration examples for workload definition.)
```

--------------------------------

### Show Version Information

Source: https://docs.nosqlbench.io/user-guide/cli-options

Show version, long form, with artifact coordinates. This option displays detailed version information about the NoSQLBench installation.

```bash
--version
```

--------------------------------

### Detailed Op Template Example (YAML, JSON, Ops)

Source: https://docs.nosqlbench.io/reference/workload_definition/04-op-template-basics

Provides a comprehensive example of a detailed op template, including properties like name, operation statement, bindings, tags, parameters, and description. This is demonstrated across YAML, JSON, and the 'ops' format.

```yaml
ops:
  op1:
    name: special-op-name
    op: select * from ks1.tb1;
    bindings:
      binding1: NumberNameToString();
    tags:
      block: schema
    params:
      prepared: false
    description: This is just an example operation

```

```json
{
  "ops": {
    "op1": {
      "bindings": {
        "binding1": "NumberNameToString();"
      },
      "description": "This is just an example operation",
      "name": "special-op-name",
      "op": "select * from ks1.tb1;",
      "params": {
        "prepared": false
      },
      "tags": {
        "block": "schema"
      }
    }
  }
}

```

```json
[
  {
    "bindings": {
      "binding1": "NumberNameToString();"
    },
    "description": "This is just an example operation",
    "name": "block0--special-op-name",
    "op": {
      "stmt": "select * from ks1.tb1;"
    },
    "params": {
      "prepared": false
    },
    "tags": {
      "block": "schema",
      "name": "block0--special-op-name",
      "block": "block0"
    }
  }
]

```

--------------------------------

### Executing JDBC Workload

Source: https://docs.nosqlbench.io/reference/drivers

This section provides an example of how to invoke a JDBC workload using the NoSQLBench command-line tool. It outlines the necessary parameters for the JDBC driver and other NoSQLBench engine parameters.

```APIDOC
## Executing JDBC Workload

### Description
An example of invoking a JDBC workload using the NoSQLBench command-line tool, including driver-specific and engine parameters.

### Method
Command Line Tool

### Endpoint
N/A

### Parameters
#### Command Line Arguments
- **run** - The command to execute a workload.
- **driver** (string) - Must be `jdbc`. Required.
- **workload** (string) - Path to the workload YAML file. Required.
- **cycles** (integer) - Number of cycles to run. Optional. Default depends on workload.
- **threads** (integer) - Number of threads to use. Optional. Default depends on workload.
- **url** (string) - URL of the database cluster. Default is `jdbc:postgresql://`. Optional.
- **serverName** (string) - Hostname of the database server. Default is `localhost`. Optional.
- **portNumber** (integer) - Port number of the database server. Default is `5432`. Optional.
- **databaseName** (string) - Name of the database to connect to. Default is the user name. Optional.
- **-vv** - Verbose logging flag. Optional.
- **--show-stacktraces** - Flag to show stack traces on error. Optional.

### Request Example
```bash
<nb_cmd> run driver=jdbc workload="/path/to/workload.yaml" cycles=1000 threads=100 url="jdbc:postgresql://" serverName=localhost portNumber=5432 databaseName=defaultdb ... -vv --show-stacktraces
```

### Response
N/A (This is a command-line execution example)

### Notes
- `<nb_cmd>` can be `./nb` (binary) or `java -jar nb5.jar`.
- The `threads` parameter determines the number of clients created, which share connections from the Hikari Connection Pool.
```

--------------------------------

### Workload Definition with Driver Configuration (YAML)

Source: https://docs.nosqlbench.io/user-guide/core-activity-params

An example of a workload definition in YAML format, specifying the 'stdout' driver and an operation template. This illustrates how to assign a driver to an op template within a workload file.

```yaml
# file test.yaml
ops:
 op1:
  op:
   driver: stdout
   stmt: "example {{Identity()}}"

```

--------------------------------

### Copy Built-in Workload with nb5 CLI

Source: https://docs.nosqlbench.io/workloads-101/00-designing-workloads

Demonstrates how to copy a built-in NoSQLBench workload to a local directory using the nb5 command-line interface. This is useful for using existing workloads as a starting point for new designs.

```bash
# find a workload you want to copy
nb5 --list-workloads

# copy a workload to your local directory
nb5 --copy cql-iot

```

--------------------------------

### NoSQLBench Scenario Script Example

Source: https://docs.nosqlbench.io/user-guide/cli-scripting

This code snippet demonstrates a multi-line NoSQLBench scenario script. It shows how to chain commands using backslashes for readability, defining activities, wait times, and stop conditions. Each line represents a distinct command in the scenario.

```bash
1| ./nb5 \
  
---|---
2| start driver=stdout alias=a cycles=100K workload=cql-iot tags=block:main \
  
3| start driver=stdout alias=b cycles=200K workload=cql-iot tags=block:main \
  
4| waitmillis 10000 \
  
5| await a \
  
6| stop b
```

--------------------------------

### Detailed Op Template Example with Bindings

Source: https://docs.nosqlbench.io/user-guide/op-templates

An example of a more detailed op template that utilizes bindings and blocks for defining operations. This structure allows for more complex configurations and reusability of defined bindings.

```yaml
bindings:
  binding1: Combinations('a-z')
blocks:
 warmup-block:
  ops:
   op1:
    op:
     prepared: "example {binding1} body"
```

--------------------------------

### Command Line Parameter Syntax

Source: https://docs.nosqlbench.io/user-guide/core-activity-params

Demonstrates the basic syntax for passing activity parameters as named arguments on the command line. Parameters are specified in a '<param>=<value>' format.

```bash
... <param>=<value> ...
```

--------------------------------

### Define a Basic Op Template in NoSQLBench

Source: https://docs.nosqlbench.io/workloads-101/07-more-op-templates

This example shows a basic operation template structure in NoSQLBench. It defines an operation type 'GET' and specifies an identifier with a unique ID and group. This structure is fundamental for defining operations within NoSQLBench workloads.

```yaml
ops:
 s1:
  type: GET
  ident:
   uid: 234
   group: 2

```

--------------------------------

### Error Handler Chain Configuration Example

Source: https://docs.nosqlbench.io/user-guide/error-handlers

This example demonstrates a handler chain with multiple error patterns and corresponding handler verbs. It shows how different error types can be handled distinctly, including ignoring specific errors, warning on others, and applying a default handler.

```yaml
errors=Invalid.*:ignore;Runtime.*:warn,histogram;counter,42
```

--------------------------------

### CSVSampler Example Usage

Source: https://docs.nosqlbench.io/reference/bindings/funcref-general

An example demonstrating how to use the CSVSampler function with specific column names and data sources.

```Java
CSVSampler('USPS','n/a','name','census_state_abbrev')
```

--------------------------------

### Use Bindings with Stdout Activity

Source: https://docs.nosqlbench.io/workloads-101/03-data-bindings

This example demonstrates how to use the defined bindings with the stdout activity type in NoSQLBench. It shows a complete activity YAML configuration that includes the bindings section and illustrates how the stdout activity can construct a statement template from these bindings, outputting generated data in CSV format.

```yaml
[test]$ cat > stdout-test.yaml
    bindings:
     alpha: Identity()
     beta: NumberNameToString()
     gamma: Combinations('0-9A-F;0-9;A-Z;_;p;r;o;')
     delta: WeightedStrings('one:1;six:6;three:3;')
# EOF (control-D in your terminal)

[test]$ ./nb5 run driver=stdout workload=stdout-test cycles=10
0,zero,00A_pro,six
1,one,00B_pro,six
2,two,00C_pro,three
3,three,00D_pro,three
4,four,00E_pro,six
5,five,00F_pro,six
6,six,00G_pro,six
7,seven,00H_pro,six
8,eight,00I_pro,six
9,nine,00J_pro,six

```

--------------------------------

### Define Bindings (JSON)

Source: https://docs.nosqlbench.io/reference/workload_definition/02-workload-structure

This JSON example defines 'bindings' which are functions used to generate data for operations. It maps binding names to their respective function chain definitions.

```json
{
  "bindings": {
    "cycle": "Identity();",
    "name": "NumberNameToString();"
  }
}
```

--------------------------------

### Example Workload with Op Tags - NoSQLBench

Source: https://docs.nosqlbench.io/workloads-101/05-op-tags

An example of a workload configuration in YAML that includes Op Tags ('name: foxtrot', 'unit: bravo') and a simple statement. This serves as a basis for demonstrating tag filtering.

```yaml
# stdout-test.yaml
tags:
 name: foxtrot
 unit: bravo
statements:
 - "I'm alive!\n"
```

--------------------------------

### Define Bindings in NoSQLBench Workloads

Source: https://docs.nosqlbench.io/user-guide/advanced-topics/binding-concepts

This example shows how to define two basic bindings in a NoSQLBench workload: 'numbers' using NumberNameToString() and 'names' using FirstNames(). Bindings are named recipes for procedural generation.

```yaml
bindings:
 numbers: NumberNameToString()
 names: FirstNames()

```

--------------------------------

### Define Multiple Op Templates (YAML)

Source: https://docs.nosqlbench.io/workloads-101/01-op-templates

This example demonstrates how to define multiple op templates in a single YAML file. Each item in the 'ops' list represents a distinct operation template. The content is free-form and interpreted by the activity type.

```yaml
ops:
  - This is a statement, and the file format doesn't know how statements will be used!
  - submit job {alpha} on queue {beta} with options {gamma};
```

--------------------------------

### Params at Doc Level (YAML)

Source: https://docs.nosqlbench.io/reference/workload_definition/06-op-template-variations

This YAML example shows parameters defined at the document level, outside of any specific op template. These parameters can be applied globally or to subsequent operations.

```yaml
params:
  pname: pvalue
ops: "my test op"

```

--------------------------------

### Generate Sample CQL Insert Statements

Source: https://docs.nosqlbench.io/getting-started/02-scenarios

These are example CQL INSERT statements generated by NoSQLBench for the 'cql-keyvalue' workload. They insert data into the 'baselines.keyvalue' table with sequential keys and deterministically generated values.

```cql
insert into baselines.keyvalue (key, value) values (0,382062539);
insert into baselines.keyvalue (key, value) values (1,774912474);
insert into baselines.keyvalue (key, value) values (2,949364593);
insert into baselines.keyvalue (key, value) values (3,352527683);
insert into baselines.keyvalue (key, value) values (4,351686621);
insert into baselines.keyvalue (key, value) values (5,114304900);
insert into baselines.keyvalue (key, value) values (6,439790106);
insert into baselines.keyvalue (key, value) values (7,564330072);
insert into baselines.keyvalue (key, value) values (8,296173906);
insert into baselines.keyvalue (key, value) values (9,97405552);
```

--------------------------------

### Execute Named Scenarios with NoSQLBench CLI

Source: https://docs.nosqlbench.io/workloads-101/11-named-scenarios

Examples of how to execute named scenarios using the NoSQLBench command-line interface. It shows running the 'default' scenario, a specific named scenario like 'longrun', and combining scenarios from multiple workload files.

```bash
# runs the scenario named 'default' if it exists, or throws an error if it does not.
nb5 myworkloads
# or
nb5 myworkloads default

# runs the named scenario 'longrun' if it exists, or throws an error if it does not.
nb5 myworkloads longrun

# runs the named scenario 'longrun' if it exists, or throws an error if it does not.
# this is simply the canonical form which is more verbose, but more explicit.
nb5 scenario myworkloads longrun

# run multiple named scenarios from one workload, and then some from another
nb5 scenario myworkloads longrun default longrun scenario another.yaml name1 name2

```

--------------------------------

### NoSQLBench Basic Parameter Override Example

Source: https://docs.nosqlbench.io/workloads-101/11-named-scenarios

Demonstrates overriding the 'cycles' parameter for scenario 's1' from the default value to '7' when running the workload. The output shows cycles from 0 to 6, indicating the override was successful.

```bash
$ nb5 basics s1 cycles=7
Logging to logs/scenario_20200324_205121_554.log
cycle=0
cycle=1
cycle=2
cycle=3
cycle=4
cycle=5
cycle=6

```

--------------------------------

### Display Help Information (CLI)

Source: https://docs.nosqlbench.io/user-guide

The '--help' option displays general help information for the NoSQLBench CLI. Short options like '-v' increase verbosity, while long options like '--help' modify general behavior or provide more details. Un-dashed words are commands, and 'option=value' pairs are arguments to the preceding command.

```bash
--help
```

--------------------------------

### Named Statement Form with Shorthand Parameters

Source: https://docs.nosqlbench.io/workloads-101/07-more-op-templates

Presents an equivalent configuration to the previous example but uses the `<name>: <statement>` form for mapping statements by name. 'parm1: pvalue1' is shown as shorthand for setting values in the params map.

```yaml
statements:
  - foostmt: "{alpha},{beta}\n"
    parm1: pvalue1
    bindings:
      beta: Combinations('COMBINATIONS;')
    tags:
      tag1: tvalue1
```

--------------------------------

### Named Op Templates with YAML Pipe (YAML)

Source: https://docs.nosqlbench.io/workloads-101/01-op-templates

This example shows how to name individual op templates using a key-value structure within the YAML. Each op is assigned a name (e.g., 's1', 's2') followed by its definition, often using the YAML pipe for multi-line content. Unnamed ops are auto-generated.

```yaml
ops:
  - s1: |
    This is a statement, and the file format doesn't
    know how statements will be used!
  - s2: |
    submit job {alpha} on queue {beta} with options {gamma};
```

--------------------------------

### Get Milliseconds at Start of Year

Source: https://docs.nosqlbench.io/reference/bindings/funcref-datetime

Returns the epoch milliseconds representing the start of the year for a given epoch millisecond timestamp. The function supports specifying a timezone for accurate year-start calculation.

```Java
long ToMillisAtStartOfYear();
long ToMillisAtStartOfYear(String timezoneId);
```

--------------------------------

### Stdout Activity Statement with Token Substitution

Source: https://docs.nosqlbench.io/reference/drivers/stdout

This example illustrates a simple statement within the stdout activity that uses curly braces to reference binding names like 'minutes' and 'hour'. These tokens will be replaced with their corresponding values during execution.

```yaml
ops:
 op1: "It is {minutes} past {hour}."

```

--------------------------------

### Get Milliseconds at Start of Next Named Weekday

Source: https://docs.nosqlbench.io/reference/bindings/funcref-datetime

Determines the epoch milliseconds at the start of the next occurrence of a specified weekday, excluding the current day. The calculation can be localized to a specific timezone.

```Java
long ToMillisAtStartOfNextNamedWeekDay();
long ToMillisAtStartOfNextNamedWeekDay(String weekday);
long ToMillisAtStartOfNextNamedWeekDay(String weekday, String timezoneId);
```

--------------------------------

### Run stdout Activity with DML Tag Filtering and Cycle Range

Source: https://docs.nosqlbench.io/reference/drivers/stdout

This example demonstrates running a stdout activity, filtering for 'dml' statements, specifying 100 cycles, and defining a cycle range from 1000 to 11000. It also includes 'filename=test.csv' to output to a file.

```bash
nb5 driver=stdout workload=stdout-test tags=group:'dml.*' cycles=1000..11000 filename=test.csv

```

--------------------------------

### Get Milliseconds at Start of Named Weekday

Source: https://docs.nosqlbench.io/reference/bindings/funcref-datetime

Calculates the epoch milliseconds at the start of the most recent occurrence of a specified weekday, optionally considering a given timezone. It can include the current day if it matches the criteria.

```Java
long ToMillisAtStartOfNamedWeekDay();
long ToMillisAtStartOfNamedWeekDay(String weekday);
long ToMillisAtStartOfNamedWeekDay(String weekday, String timezoneId);
```

--------------------------------

### Get Milliseconds at Start of Month

Source: https://docs.nosqlbench.io/reference/bindings/funcref-datetime

Returns the epoch milliseconds at the start of the month for a given epoch millisecond value. It supports timezone specification or defaults to UTC, useful for month-aligned time operations.

```Java
long ToMillisAtStartOfMonth()
long ToMillisAtStartOfMonth(String timezoneId)
```

--------------------------------

### Advanced Statement Configuration with Overrides

Source: https://docs.nosqlbench.io/workloads-101/07-more-op-templates

Demonstrates a detailed statement configuration where bindings, parameters, and tags are defined. These settings take precedence over any enclosing block or document settings when names match. 'freeparam3' is an example of a free parameter.

```yaml
statements:
  - name: foostmt
    stmt: "{alpha},{beta}\n"
    bindings:
      beta: Combinations('COMBINATIONS;')
    params:
      parm1: pvalue1
    tags:
      tag1: tvalue1
    freeparam3: a value, as if it were assigned under the params block.
```

--------------------------------

### Get Milliseconds at Start of Minute

Source: https://docs.nosqlbench.io/reference/bindings/funcref-datetime

Returns the epoch milliseconds at the start of the minute for a given epoch millisecond value. This function can use a specified timezone or default to UTC, facilitating minute-level time alignment.

```Java
long ToMillisAtStartOfMinute()
long ToMillisAtStartOfMinute(String timezoneId)
```

--------------------------------

### List Available Drivers (CLI)

Source: https://docs.nosqlbench.io/user-guide

The '--list-drivers' option is used to discover and list all available database drivers that NoSQLBench can utilize.

```bash
--list-drivers
```

--------------------------------

### Get Milliseconds at Start of Hour

Source: https://docs.nosqlbench.io/reference/bindings/funcref-datetime

Returns the epoch milliseconds at the start of the hour for a given epoch millisecond value. It allows for timezone specification or defaults to UTC, enabling precise hour-aligned time calculations.

```Java
long ToMillisAtStartOfHour()
long ToMillisAtStartOfHour(String timezoneId)
```

--------------------------------

### NoSQLBench Scenario Script Narrative

Source: https://docs.nosqlbench.io/user-guide/cli-scripting

This code snippet provides a narrative explanation for each line of the NoSQLBench scenario script. It clarifies the purpose of each command, such as invoking the nb5 tool, starting activities with specified cycles, waiting for a duration, awaiting activity completion, and stopping activities.

```bash
1| # nb5 is invoked
  
---|---
2| # An activity named 'a' is started, with 100K cycles of work.
  
3| # An activity named 'b' is started, with 200K cycles of work.
  
4| # While these activities run, the scenario script waits for ten seconds.
  
5| # The scenario blocks, waiting for activity 'a' to complete its 100K cycles.
  
6| # Activity 'b' is immediately stopped.
```

--------------------------------

### Get Milliseconds at Start of Day

Source: https://docs.nosqlbench.io/reference/bindings/funcref-datetime

Returns the epoch milliseconds at the start of the day for a given epoch millisecond value. It supports specifying a timezone ID or defaults to UTC. This is useful for aligning time values to the beginning of a day.

```Java
long ToMillisAtStartOfDay()
long ToMillisAtStartOfDay(String timezoneId)
```

--------------------------------

### List Available Scenarios (CLI)

Source: https://docs.nosqlbench.io/user-guide

Use the '--list-scenarios' option to retrieve a list of all predefined or custom scenarios available for execution within NoSQLBench.

```bash
--list-scenarios
```

--------------------------------

### Get Elapsed Nanoseconds with ElapsedNanoTime

Source: https://docs.nosqlbench.io/reference/bindings/funcref-general

ElapsedNanoTime returns the elapsed nanosecond time since the process started. Caution: This function does not produce deterministic test data.

```Java
long ElapsedNanoTime()
```

--------------------------------

### Get Milliseconds at Start of Second

Source: https://docs.nosqlbench.io/reference/bindings/funcref-datetime

Calculates the epoch milliseconds corresponding to the beginning of the second for a given epoch millisecond timestamp. This operation can be performed with or without specifying a timezone.

```Java
long ToMillisAtStartOfSecond();
long ToMillisAtStartOfSecond(String timezoneId);
```

--------------------------------

### Create CQL Keyspace and Table

Source: https://docs.nosqlbench.io/getting-started/02-scenarios

This snippet shows how to create a new keyspace named 'baselines' with simple replication and a 'keyvalue' table within it. The table has a text key and a text value.

```cql
CREATE KEYSPACE baselines
 WITH replication = {'class': 'SimpleStrategy', 'replication_factor': '1'}
 AND durable_writes = true;

CREATE TABLE baselines.keyvalue (
    key text PRIMARY KEY,
    value text
)
```

--------------------------------

### Cycles Configuration

Source: https://docs.nosqlbench.io/user-guide/core-activity-params

The `cycles` parameter defines the range of cycle counts for an activity. It can be a single count or a range (min..max), specifying the starting and ending point for operations.

```APIDOC
## cycles

### Description
Determines the starting and ending point for an activity's cycles, defining the range of values used as seed values for each operation.

### Method
Not Applicable (Configuration Parameter)

### Endpoint
Not Applicable (Configuration Parameter)

### Parameters
#### Query Parameters
- **cycles** (string) - Optional - The cycle count or range. Can be a single count (e.g., `500`), a large number with suffix (e.g., `20M`), or a range (e.g., `2k..3k`). The range is a closed-open interval [min, max).

### Request Example
```
cycles=500
cycles=20M
cycles=2k..3k
```

### Response
#### Success Response (200)
Not Applicable (Configuration Parameter)

#### Response Example
Not Applicable (Configuration Parameter)
```

--------------------------------

### Get Milliseconds at Start of Next Day

Source: https://docs.nosqlbench.io/reference/bindings/funcref-datetime

Returns the epoch milliseconds at the beginning of the day immediately following the day represented by the input epoch milliseconds. This function can also specify a timezone for the calculation.

```Java
long ToMillisAtStartOfNextDay();
long ToMillisAtStartOfNextDay(String timezoneId);
```

--------------------------------

### Execute NoSQLBench Workload from Command Line

Source: https://docs.nosqlbench.io/workloads-101/03-data-bindings

This command executes the 'stdout-test' workload using the 'stdout' driver for 10 cycles. It demonstrates how to run a NoSQLBench workload and shows the expected output based on the defined statements and bindings.

```bash
[test]$ ./nb5 run driver=stdout workload=stdout-test cycles=10
```

--------------------------------

### Start and Stop Timers for Operations

Source: https://docs.nosqlbench.io/user-guide/core-op-fields

Instrument operations by starting and stopping named timers immediately before and after operations. These timers are started and stopped unconditionally, including failed operations. Measurements are aggregated across all threads for a given timer name.

```yaml
ops:
  op1:
    op: "example stmt1"
    start-timers: stanza1, stanza2
  op2:
    op: "example stmt2"
    stop-timers: stanza1
  op3:
    op: "example stmt"
    stop-timers: stanza2
```

--------------------------------

### TCP Sessions and Client Instances

Source: https://docs.nosqlbench.io/reference/drivers/http

Explains how TCP sessions and native client instances are managed based on the 'space' binding.

```APIDOC
## TCP Sessions & Clients

### Description
Details the management of TCP sessions and native HTTP client instances within NoSQLBench.

### Client Instantiation
Client instances are created per unique `space` value. By default, the `space` is set to `default`, meaning all threads share a single HTTP client instance.

### Per-Thread Clients
To create a new HTTP client instance per thread, configure the `space` binding as follows:
- Using an op template parameter: `space: {space}` where `space` is bound to `ThreadNumToInteger()`.
- Using an inline op field: `space: {(ThreadNumToInteger())}`.

### Binding Functions
Any binding function can be used for the `space` op field. However, using functions like `Identity()` can lead to excessive client instantiation and should be avoided.
```

--------------------------------

### Specify Single-Op Workload via Command Line

Source: https://docs.nosqlbench.io/index

Illustrates how to define and execute a single-operation workload directly from the command line using the 'op="..."' parameter. This simplifies testing and utility usage.

```shell
nb5 <workload-file> op="<operation-definition>"
```

--------------------------------

### Run Mixed Read/Write Workload with NoSQLBench

Source: https://docs.nosqlbench.io/getting-started/02-scenarios

Executes a mixed read/write workload using the nb5 command-line tool. It specifies the driver, workload, tags for query blocks, number of cycles, cycle rate, and threads for concurrency. The output shows progress and completion status of the workload.

```bash
./nb5 run driver=cql workload=cql-keyvalue tags='block:main.*' \
 cycles=50k cyclerate=5000 threads=50 --progress console:1s ...
```

--------------------------------

### Execute a NoSQLBench Scenario Script

Source: https://docs.nosqlbench.io/user-guide/advanced-topics/scenario-scripting

This command executes a NoSQLBench scenario defined in a JavaScript file. It allows users to run custom testing configurations and leverage the full programmatic power of NoSQLBench.

```bash
nb5 script myfile.js
```

--------------------------------

### Splitting Cycles Across Multiple Client Nodes

Source: https://docs.nosqlbench.io/user-guide/advanced-topics/testing-at-scale/client-sizing

Demonstrates how to divide the total number of cycles across multiple client nodes to distribute the workload evenly. This prevents redundant execution of operations when scaling out.

```shell
# Single-node test
cycles=1M

# Split into two nodes
# Node 1
cycles=500K

# Node 2
cycles=500k..1M
```

--------------------------------

### Inline Binding Recipes

Source: https://docs.nosqlbench.io/index

Shows how to define binding recipes directly within the workload definition using the '{{Identity()}}' syntax. This is useful for simple, one-off bindings.

```shell
op=... {{Identity()}} ...
```

--------------------------------

### Define List of Un-named Scenario Steps (JSON)

Source: https://docs.nosqlbench.io/reference/workload_definition/02-workload-structure

This JSON snippet demonstrates defining a scenario named 'default' as an array of un-named steps. Each element in the array is a command string representing a step in the scenario.

```json
{
  "scenarios": {
    "default": [
      "run alias=first driver=diag cycles=10",
      "run alias=second driver=diag cycles=10"
    ]
  }
}
```

--------------------------------

### Anonymous Fields with Scoped Params (JSON)

Source: https://docs.nosqlbench.io/reference/workload_definition/06-op-template-variations

This JSON example demonstrates anonymous fields and a 'params' object within an op template. The parameters are associated with the operation.

```json
{
  "ops": {
    "op1": {
      "field1": "select * from ks1.tb1;",
      "field2": "field 2 value",
      "params": {
        "paramname1": "paramvalue1"
      }
    }
  }
}

```

--------------------------------

### List Available Metrics (CLI)

Source: https://docs.nosqlbench.io/user-guide

The '--list-metrics <activity type> [ <activity name> ]' option provides a list of metrics that are available for scripting and monitoring for a specific activity type and optionally, a named activity.

```bash
--list-metrics <activity type> [ <activity name> ]
```

--------------------------------

### Define List of Un-named Scenario Steps (YAML)

Source: https://docs.nosqlbench.io/reference/workload_definition/02-workload-structure

This YAML shows how to define a scenario named 'default' as a list of un-named steps. Each item in the list is a command string to be executed in order.

```yaml
scenarios:
  default:
    - run alias=first driver=diag cycles=10
    - run alias=second driver=diag cycles=10

```

--------------------------------

### ModuloToInteger: Perform modulo division to get Integer

Source: https://docs.nosqlbench.io/reference/bindings/funcref-general

Returns an integer value as the result of modulo division with the specified divisor. The input is a long, and the divisor is an int.

```Java
ModuloToInteger(modulo)
```

--------------------------------

### Copy Workload File (CLI)

Source: https://docs.nosqlbench.io/user-guide

The '--copy <name>' option allows you to copy a specified workload or other configuration file to your local directory, serving as a template for customization.

```bash
--copy <name>
```

--------------------------------

### Args File Format in NoSQLBench

Source: https://docs.nosqlbench.io/user-guide/advanced-topics/configuration_techniques/argsfiles

An args file in NoSQLBench is a simple text file where each line contains a single command-line argument. This format allows for easy management and customization of default settings for NoSQLBench commands.

```plaintext
--docker-metrics
--annotate all
--grafana-baseurl http://localhost:3000/
```

--------------------------------

### Get First Lines of a File with FirstLines

Source: https://docs.nosqlbench.io/reference/bindings/funcref-general

FirstLines retrieves the first specified number of lines from a file. It can take a file path and an optional integer for the number of lines.

```Java
Object FirstLines(String filePath)
Object FirstLines(String filePath, Integer numberOfLines)
```

--------------------------------

### Errors Configuration

Source: https://docs.nosqlbench.io/user-guide/core-activity-params

The `errors` parameter specifies how to handle exceptions thrown during operation execution. It allows configuring named exceptions with specific handler verbs.

```APIDOC
## errors

### Description
Specifies how to handle exceptions thrown during the execution of an operation within a cycle. Allows configuring named exceptions with handler verbs.

### Method
Not Applicable (Configuration Parameter)

### Endpoint
Not Applicable (Configuration Parameter)

### Parameters
#### Query Parameters
- **errors** (string) - Optional - The error handler specification. Defaults to `errors=stop`. Can be configured with named exceptions and handler verbs.

### Request Example
```
errors=stop
errors=on_error=continue
```

### Response
#### Success Response (200)
Not Applicable (Configuration Parameter)

#### Response Example
Not Applicable (Configuration Parameter)
```

--------------------------------

### Loading Args Files in NoSQLBench

Source: https://docs.nosqlbench.io/user-guide/advanced-topics/configuration_techniques/argsfiles

Specifies how to load arguments from an args file. The `--argsfile <path>` variant warns if the file is missing, `--argsfile-optional <path>` silently ignores missing files, and `--argsfile-required <path>` throws an error. The default args file is located at `$NBSTATEDIR/argsfile` and is loaded automatically if present.

```bash
--argsfile <path>
--argsfile-optional <path>
--argsfile-required <path>
```

```bash
--argsfile-optional "$NBSTATEDIR/argsfile"
```

--------------------------------

### Load JSON and Jsonnet Workloads

Source: https://docs.nosqlbench.io/index

Demonstrates how to load workload templates directly from JSON or Jsonnet files. Includes an option to perform a dry run of Jsonnet rendering for validation.

```shell
nb5 <workload-file.json>
nb5 <workload-file.jsonnet>
nb5 <workload-file.jsonnet> dryrun=jsonnet
```

--------------------------------

### NumberNameToString: Convert Number to Spelled-Out String

Source: https://docs.nosqlbench.io/reference/bindings/funcref-general

Provides the spelled-out name of a number. For example, an input of 7 would yield 'seven'. The maximum input value is limited to 999,999,999.

```Java
long -> NumberNameToString() -> String
```

--------------------------------

### Accept License Script

Source: https://docs.nosqlbench.io/dev-guide/contributing/pull-requests

A utility script located in the `scripts` directory can be used to automatically apply the correct APLv2 license headers and copyright information to files. This is useful after the build fails due to missing or incorrect license headers.

```bash
scripts/accept_license.sh
```

--------------------------------

### Define Multiple Named Scenario Steps (JSON)

Source: https://docs.nosqlbench.io/reference/workload_definition/02-workload-structure

This JSON snippet represents a scenario named 'default' containing multiple named steps ('step1', 'step2'). Each step is defined by a command string with associated parameters.

```json
{
  "scenarios": {
    "default": {
      "step1": "run alias=first driver=diag cycles=10",
      "step2": "run alias=second driver=diag cycles=10"
    }
  }
}
```

--------------------------------

### Preview CQL Insert Statements with NoSQLBench

Source: https://docs.nosqlbench.io/getting-started/02-scenarios

This command uses NoSQLBench with the 'stdout' driver to preview the CQL INSERT statements generated by the 'cql-keyvalue' workload. This is useful for verifying data generation before actual writes.

```bash
./nb5 run driver=stdout workload=cql-keyvalue
```

--------------------------------

### LongFlow for Combining LongUnaryOperators - NoSQLBench IO

Source: https://docs.nosqlbench.io/reference/bindings/funcref-functional

LongFlow combines multiple LongUnaryOperators into a single function. An example demonstrates creating an operator that adds 3 and then multiplies the result by 6.

```java
long -> LongFlow(function.LongUnaryOperator[]...: ops) -> long
// _example:_ `LongFlow(Add(3),Mul(6))`
// _Create an integer operator which adds 3 and multiplies the result by 6_
```

--------------------------------

### Pinning Options to Args File in NoSQLBench

Source: https://docs.nosqlbench.io/user-guide/advanced-topics/configuration_techniques/argsfiles

The `--pin` meta-option adds the subsequent command-line argument to the active args file. This is useful for setting persistent global defaults. If the option already exists with the same value, it's skipped; otherwise, it's added. Pinning global options without commands prevents scenario execution, making it suitable for argument configuration.

```bash
./nb --pin --docker-metrics-at metricsnode --pin --annotate all
```
Tokens:
Raw