Apache Kvrocks

https://kvrocks.apache.org/docs
Admin
Apache Kvrocks is a distributed key-value NoSQL database that uses RocksDB as storage engine and is...
Tokens:26,377
Snippets:187
Trust Score:10
Update:6 months ago
Show doc for...
Tokens:
Raw
### Create Namespaces

Source: https://kvrocks.apache.org/docs/namespace

Initial setup commands to create multiple namespaces with specific tokens.

```bash
127.0.0.1:6666> namespace add ns1 token1  
127.0.0.1:6666> namespace add ns2 token2
```

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

### Install Kvrocks Dependencies on CentOS/RedHat

Source: https://kvrocks.apache.org/docs/getting-started

Installs development tools, including devtoolset-11, and downloads/installs CMake for compiling Kvrocks on CentOS/RedHat.

```bash
sudo yum install -y centos-release-scl-rh  
sudo yum install -y git devtoolset-11 autoconf automake libtool libstdc++-static python3 openssl-devel  
# download and install cmake via https://cmake.org/download  
wget https://github.com/Kitware/CMake/releases/download/v3.26.4/cmake-3.26.4-linux-x86_64.sh -O cmake.sh  
sudo bash cmake.sh --skip-license --prefix=/usr  
# enable gcc and make in devtoolset-11  
source /opt/rh/devtoolset-11/enable  
```

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

### kvrocks2redis Configuration

Source: https://kvrocks.apache.org/docs/kvrocks2redis

Example configuration file settings for defining log levels, data directories, and target Redis instances.

```text
# The value should be INFO, WARNING, ERROR, FATAL  
log-level INFO  
  
# Determine whether to run on the daemonize mode or not  
# Default: no  
daemonize no  
  
# Where to read and parse the local DB, it should be same as the `dir` in kvrocks.conf  
# Default: ./data  
data-dir ./data  
  
# Where to store the output like the sync sequence and AOF file  
# Default: ./  
output-dir ./  
  
# The source host:port to sync change streams after parsing the local DB  
# kvrocks <kvrocks_ip> <kvrocks_port> [<kvrocks_auth>]  
kvrocks 127.0.0.1 6666  
  
# If the source Kvrocks enabled the cluster mode, should enable it here as well.  
# Default: no  
cluster-enabled no  
  
# Synchronize the specified namespace data to the specified Redis DB.  
# Warning: It will flush the target redis DB data first before syncing the data.  
#  
# namespace.{namespace} <redis_ip> <redis_port> [<redis_auth> <redis_db_number>]  
# Default redis_db_number is 0  
namespace.__namespace 127.0.0.1 6379
```

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

### Install Kvrocks Dependencies on macOS

Source: https://kvrocks.apache.org/docs/getting-started

Installs required tools like git, cmake, and openssl using Homebrew, with a note to force-link openssl if needed.

```bash
brew install git cmake autoconf automake libtool openssl  
# please link openssl by force if it still cannot be found after installing  
brew link --force openssl  
```

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

### Install Kvrocks Dependencies on Ubuntu/Debian

Source: https://kvrocks.apache.org/docs/getting-started

Installs necessary build tools and libraries for compiling Kvrocks on Ubuntu or Debian-based systems.

```bash
sudo apt update  
sudo apt install -y git build-essential cmake libtool python3 libssl-dev  
```

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

### INFO Command Example

Source: https://kvrocks.apache.org/docs/info-sections

This is a sample output of the INFO command, illustrating the structure and types of information returned. It includes sections for server, clients, memory, persistence, stats, replication, CPU, commandstats, cluster, and keyspace.

```text
# Server  
version:unstable  
kvrocks_version:unstable  
redis_version:4.0.0  
git_sha1:0a2dcee  
kvrocks_git_sha1:0a2dcee  
os:Darwin 19.4.0 x86_64  
gcc_version:4.2.1  
arch_bits:64  
process_id:1467  
tcp_port:6666  
uptime_in_seconds:8  
uptime_in_days:0  
  
# Clients  
maxclients:10000  
connected_clients:1  
monitor_clients:0  
blocked_clients:0  
  
# Memory  
used_memory_rss:19558400  
used_memory_rss_human:18.65M  
used_memory_lua:35840  
used_memory_lua_human:35.00K  
used_memory_startup:20357120  
  
# Persistence  
loading:0  
bgsave_in_progress:0  
last_bgsave_time:1689584510  
last_bgsave_status:ok  
last_bgsave_time_sec:0  
  
# Stats  
total_connections_received:1  
total_commands_processed:2  
instantaneous_ops_per_sec:0  
total_net_input_bytes:23  
total_net_output_bytes:8231  
instantaneous_input_kbps:0  
instantaneous_output_kbps:0  
sync_full:0  
sync_partial_ok:0  
sync_partial_err:0  
pubsub_channels:0  
pubsub_patterns:0  
  
# Replication  
role:master  
connected_slaves:0  
master_repl_offset:0  
  
# CPU  
used_cpu_sys:0  
used_cpu_user:0  
  
# Commandstats  
cmdstat_command:calls=1,usec=904,usec_per_call=904  
cmdstat_info:calls=1,usec=0,usec_per_call=0  
  
# Cluster  
cluster_enabled:0  
  
# Keyspace  
# Last scan db time: Thu Jan  1 08:00:00 1970  
db0:keys=0,expires=0,avg_ttl=0,expired=0  
sequence:0  
used_db_size:0  
max_db_size:0  
used_percent: 0%  
disk_capacity:499963174912  
used_disk_size:266419978240  
used_disk_percent: 53%  
  

```

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

### Run Kvrocks with Docker

Source: https://kvrocks.apache.org/docs/getting-started

Pulls the latest Kvrocks Docker image and starts a container, exposing the default port 6666.

```bash
docker run -it -p 6666:6666 apache/kvrocks --bind 0.0.0.0  
```

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

### Get Query Execution Plan

Source: https://kvrocks.apache.org/docs/kvrocks-search

Use FT.EXPLAIN to obtain a plan detailing how Kvrocks will execute a given query. This helps in understanding query performance.

```redis-cli
FT.EXPLAIN index query 
  [RETURN count identifier [ identifier ...]] 
  [SORTBY sortby [ ASC | DESC]] 
  [LIMIT offset num] 
  [PARAMS nargs name value [ name value ...]]  
```

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

### Get SQL Query Plan

Source: https://kvrocks.apache.org/docs/kvrocks-search

Use FT.EXPLAINSQL to obtain a query plan for SQL queries. Supports different output formats like SIMPLE, DOT, and DEBUG.

```redis-cli
FT.EXPLAINSQL sql  
  [PARAMS nargs name value [ name value ...]]   
  [SIMPLE | DOT | DEBUG]  
```

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

### Install Kvrocks Dependencies on openSUSE/SUSE

Source: https://kvrocks.apache.org/docs/getting-started

Installs required packages including GCC 11, CMake, and build tools for compiling Kvrocks on openSUSE or SUSE Linux Enterprise.

```bash
sudo zypper install -y gcc11 gcc11-c++ make wget git autoconf automake python3 curl cmake  
```

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

### RediSearch Parameterized Query Example

Source: https://kvrocks.apache.org/docs/kvrocks-search

Demonstrates the use of parameters in RediSearch queries, indicated by a '$' prefix, for dynamic value injection.

```redis
@a:[inf $num]
```

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

### Kvrocks SQL Parameterized Query Example

Source: https://kvrocks.apache.org/docs/kvrocks-search

Illustrates how to use parameters in Kvrocks SQL queries for dynamic value substitution. Parameters are prefixed with '@'.

```sql
a < @num
```

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

### Install Kvrocks Dependencies on Arch Linux

Source: https://kvrocks.apache.org/docs/getting-started

Installs necessary packages such as autoconf, cmake, and build tools for compiling Kvrocks on Arch Linux.

```bash
sudo pacman -Sy --noconfirm autoconf automake python3 git wget which cmake make gcc  
```

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

### Run Kvrocks with Docker and Admin Password

Source: https://kvrocks.apache.org/docs/getting-started

Starts a Kvrocks Docker container with an admin password set using an environment variable.

```bash
# assuming password exported on environment variable "KVROCKS_ADMIN_SECRET":  
docker run -it --rm -p 6666:6666 apache/kvrocks --bind 0.0.0.0 --requirepass $KVROCKS_ADMIN_SECRET  

# redis-cli on host looks like:  
REDISCLI_AUTH=$KVROCKS_ADMIN_SECRET redis-cli -p 6666 ping  
```

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

### Get Index Information

Source: https://kvrocks.apache.org/docs/kvrocks-search

Use FT.INFO to retrieve detailed information about a specific index, including its definition, prefixes, and fields.

```redis-cli
FT.INFO index  
```

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

### Enable Jemalloc Profiling Environment Variables

Source: https://kvrocks.apache.org/docs/how-to-profile-memory

Set these environment variables before starting Kvrocks to enable memory profiling. This is necessary for the KPROFILE command to function.

```bash
export MALLOC_CONF="prof:true,background_thread:true"
./kvrocks -c kvrocks.conf
```

```bash
MALLOC_CONF="prof:true,background_thread:true" ./kvrocks -c kvrocks.conf
```

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

### RediSearch KNN Query Example

Source: https://kvrocks.apache.org/docs/kvrocks-search

Example of a K-Nearest Neighbors (KNN) query in RediSearch syntax without prefiltering, suitable for vector search.

```redis
* => [KNN n @vec_field $vec]
```

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

### Run Kvrocks with Docker and Custom Workers

Source: https://kvrocks.apache.org/docs/getting-started

Starts a Kvrocks Docker container and sets the number of workers to 16, overriding the default.

```bash
docker run -it --rm -p 6666:6666 apache/kvrocks --bind 0.0.0.0 --workers 16  
```

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

### Run Kvrocks with Docker and Persistent Data

Source: https://kvrocks.apache.org/docs/getting-started

Starts a Kvrocks Docker container using a named volume for data persistence, specifying a custom data directory.

```bash
# create docker volume once, eg:  
docker volume create kvrocks_data  

docker run --volume kvrocks_data:/kvrocks_data \
  --interactive --tty --publish 6666:6666 apache/kvrocks --bind 0.0.0.0 --dir /kvrocks_data  

# note: the default data dir is /var/lib/kvrocks. The above example changes the location from default to /kvrocks_data.  
```

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

### Run kvrocks2redis

Source: https://kvrocks.apache.org/docs/kvrocks2redis

Execute the migration tool using a specified configuration file.

```bash
./build/kvrocks2redis -c kvrocks2redis.conf
```

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

### Run Kvrocks Server from Source Build

Source: https://kvrocks.apache.org/docs/getting-started

Executes the compiled Kvrocks server binary, loading configuration from a specified file.

```bash
./build/kvrocks -c kvrocks.conf  
```

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

### Compile Kvrocks from Source

Source: https://kvrocks.apache.org/docs/getting-started

Clones the Kvrocks repository and builds the project using the provided build script. Includes an option to use a proxy for dependency fetching.

```bash
git clone https://github.com/apache/kvrocks.git  
cd kvrocks  
./x.py build # `./x.py build -h` to check more options;  
             # especially, `./x.py build --ghproxy` will fetch dependencies via ghproxy.com.  
```

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

### Switch Between Namespaces

Source: https://kvrocks.apache.org/docs/namespace

Use the auth command with the namespace token to switch contexts and operate on isolated data.

```bash
# Use token1 to switch to ns1  
127.0.0.1:6666> auth token1  
OK  
127.0.0.1:6666> set key 100  
OK  
127.0.0.1:6666> get key  
"100"  
  
# Use token2 to switch to ns2  
127.0.0.1:6666> auth token2  
OK  
127.0.0.1:6666> set key 200  
OK  
127.0.0.1:6666> get key  
"200"  
  
# Use token1 to switch to ns1 again, the value is still 100  
127.0.0.1:6666> auth token1  
OK  
127.0.0.1:6666> get key  
"100"
```

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

### Create a New Index

Source: https://kvrocks.apache.org/docs/kvrocks-search

Use FT.CREATE to establish a new index with a specified schema. You can define the data type of keys (HASH or JSON) and prefixes for indexing.

```redis-cli
FT.CREATE index 
  [ON HASH | JSON] 
  [PREFIX count prefix [prefix ...]] 
SCHEMA field_name TAG | NUMERIC | VECTOR [FIELD PROPERTIES ...] [NOINDEX]  
       [ field_name TAG | NUMERIC | VECTOR [FIELD PROPERTIES ...] [NOINDEX]  
         ...]
```

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

### FT.CREATE

Source: https://kvrocks.apache.org/docs/kvrocks-search

Creates a new index with a specified schema.

```APIDOC
## FT.CREATE

### Description
Creates a new index with a given schema.

### Parameters
- **index** (string) - Required - The name of the index.
- **ON** (HASH | JSON) - Optional - Data type of keys to be indexed.
- **PREFIX** (count prefix) - Optional - Prefix of keys to be indexed.
- **SCHEMA** (field_name) - Required - Defines fields using TAG, NUMERIC, or VECTOR types.
```

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

### ZSet Commands Overview

Source: https://kvrocks.apache.org/docs/supported-commands

A comprehensive list of supported ZSet commands available in Kvrocks with their respective version support.

```APIDOC
## ZSet Commands Summary

### Description
Kvrocks supports a wide range of Redis-compatible ZSet commands for managing sorted sets.

### Supported Commands
- **BZMPOP** (v2.5.0) - Blocks until one or more elements are popped from one or more sorted sets.
- **BZPOPMIN** (v2.5.0) - Blocks until the element with the lowest score is popped from one or more sorted sets.
- **BZPOPMAX** (v2.5.0) - Blocks until the element with the highest score is popped from one or more sorted sets.
- **ZADD** (v1.0.0) - Adds one or more members to a sorted set, or updates the score of existing members.
- **ZCARD** (v1.0.0) - Returns the number of members in a sorted set.
- **ZCOUNT** (v1.0.0) - Counts the members in a sorted set with scores within a given range.
- **ZINCRBY** (v1.0.0) - Increments the score of a member in a sorted set.
- **ZINTERSTORE** (v1.0.0) - Computes the intersection of multiple sorted sets and stores the result in a destination sorted set.
- **ZLEXCOUNT** (v1.0.0) - Counts the members in a sorted set within a given lexicographical range.
- **ZMPOP** (v2.5.0) - Removes and returns one or more members with the lowest or highest scores from one or more sorted sets.
- **ZMSCORE** (v1.1.20) - Returns the scores of one or more members in a sorted set.
- **ZPOPMIN** (v1.0.0) - Removes and returns the member with the lowest score in a sorted set.
- **ZPOPMAX** (v1.0.0) - Removes and returns the member with the highest score in a sorted set.
- **ZRANGESTORE** (v2.5.0) - Stores a range of members from a sorted set into another sorted set.
- **ZRANGE** (v1.0.0) - Returns a range of members in a sorted set, by index.
- **ZRANGEBYLEX** (v1.0.0) - Returns a range of members in a sorted set, by lexicographical range.
- **ZRANGEBYSCORE** (v1.0.0) - Returns a range of members in a sorted set, by score.
- **ZRANK** (v1.0.0) - Determines the index of a member in a sorted set, based on score.
- **ZREM** (v1.0.0) - Removes one or more members from a sorted set.
- **ZREMRANGEBYLEX** (v1.0.0) - Removes all members in a sorted set within the given lexicographical range.
- **ZREMRANGEBYRANK** (v1.0.0) - Removes all members in a sorted set within the given index range.
- **ZREMRANGEBYSCORE** (v1.0.0) - Removes all members in a sorted set within the given score range.
- **ZREVRANK** (v1.0.0) - Determines the index of a member in a sorted set, in reverse order, based on score.
- **ZREVRANGE** (v1.0.0) - Returns a range of members in a sorted set, in reverse order, by index.
- **ZREVRANGEBYLEX** (v2.0.5) - Returns a range of members in a sorted set, in reverse order, by lexicographical range.
- **ZREVRANGEBYSCORE** (v1.0.0) - Returns a range of members in a sorted set, in reverse order, by score.
- **ZSCAN** (v1.0.0) - Incrementally iterates over elements in a sorted set.
- **ZSCORE** (v1.0.0) - Returns the score of a member in a sorted set.
- **ZUNION** (v2.5.0) - Returns the union of multiple sorted sets.
- **ZUNIONSTORE** (v1.0.0) - Computes the union of multiple sorted sets and stores the result in a destination sorted set.
- **ZINTER** (v2.8.0) - Returns the intersection of multiple sorted sets.
- **ZINTERCARD** (v2.8.0) - Computes the cardinality in the intersection of multiple sorted sets.
- **ZRANDMEMBER** (v2.8.0) - Returns one or more random members from a sorted set.
- **ZDIFF** (v2.8.0) - Returns the difference between sorted sets.
- **ZDIFFSTORE** (v2.8.0) - Stores the sorted-set difference result into a destination key.
```

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

### CONFIG

Source: https://kvrocks.apache.org/docs/supported-commands

Manages the server's configuration parameters.

```APIDOC
## CONFIG

### Description
Manages the server's configuration parameters.

### Subcommands
- **GET** - Returns the effective values of configuration parameters.
- **SET** - Sets configuration parameters in-flight.
- **REWRITE** - Persists the effective configuration to the file.

### Since Version
v1.0.0
```

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

### Get Key Count in Kvrocks

Source: https://kvrocks.apache.org/docs/faq

Kvrocks does not store the key count directly. Use `dbsize scan` to retrieve the key number by scanning the DB. The `info keyspace` command shows the last scan time and key details.

```shell
127.0.0.1:6666> dbsize scan  
OK  
  
127.0.0.1:6666> info keyspace  
# Keyspace  
# Last scan db time: Thu Mar 24 06:38:39 2022  
db0:keys=1,expires=0,avg_ttl=0,expired=0  
```

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

### INFO [section]

Source: https://kvrocks.apache.org/docs/info-sections

Retrieves server information and statistics. Optional parameters allow filtering by specific categories.

```APIDOC
## INFO [section]

### Description
The INFO command returns information and statistics about the Apache Kvrocks server in a format that is simple to parse by computers and easy to read by humans.

### Parameters
#### Query Parameters
- **section** (string) - Optional - Selects a specific section of information. Available sections: server, clients, memory, stats, replication, cpu, commandstats, cluster, keyspace, rocksdb.

### Response
#### Success Response (200)
- **bulk string** - A collection of text lines containing section names (starting with #) and field:value properties.

#### Response Example
# Server
version:unstable
kvrocks_version:unstable
redis_version:4.0.0

# Clients
connected_clients:1
```

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

### NAMESPACE

Source: https://kvrocks.apache.org/docs/supported-commands

Used to manage namespaces.

```APIDOC
## NAMESPACE

### Description
Used to manage namespaces.

### Subcommands
- **GET** - Retrieve information of namespaces.
- **SET** - Set the password of a namespace.
- **ADD** - Add a new namespace.
- **DEL** - Deletes a namespace.
- **CURRENT** - Returns the current namespace name.

### Since Version
v1.0.0
```

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

### BGSAVE

Source: https://kvrocks.apache.org/docs/supported-commands

Initiates a background save of the dataset to disk.

```APIDOC
## BGSAVE

### Description
Initiates a background save of the dataset to disk.

### Method
BGSAVE

### Since Version
v1.0.0
```

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

### Perform SQL Query

Source: https://kvrocks.apache.org/docs/kvrocks-search

Use FT.SEARCHSQL for executing SQL queries on an index. Supports parameterized queries.

```redis-cli
FT.SEARCHSQL sql  
  [PARAMS nargs name value [ name value ...]]   
```

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

### Manage Namespaces via redis-cli

Source: https://kvrocks.apache.org/docs/namespace

Commands for adding, updating, deleting, and listing namespaces. Requires the requirepass to be set for administrative access.

```bash
# Auth with the requirepass  
redis-cli -p 6666 -a ${REQUIREPASS}  
  
# Add a new namespace with the token, the namespace name must be unique.  
127.0.0.1:6666> namespace add ${NEW NAMESPACE} ${NEW TOKEN}  
  
# Update the namespace's token  
127.0.0.1:6666> namespace set ${NAMESPACE} ${NEW TOKEN}  
  
# Delete the namespace, the namespace's data WOULD NOT be deleted,  
# unless you use the `flushdb` command to flush the DB data.  
127.0.0.1:6666> namespace del ${NAMESPACE}  
  
# Get the namespace's token  
127.0.0.1:6666> namespace get ${NAMESPACE}  
  
# List namespaces  
127.0.0.1:6666> namespace get *
```

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

### List All Indexes

Source: https://kvrocks.apache.org/docs/kvrocks-search

Use FT._LIST to retrieve a list of all index names within the current namespace.

```redis-cli
FT._LIST  
```

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

### Connect to Kvrocks with redis-cli

Source: https://kvrocks.apache.org/docs/getting-started

Connects to a running Kvrocks server instance using redis-cli on the specified port.

```bash
redis-cli -p 6666  
```

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

### Hash Commands

Source: https://kvrocks.apache.org/docs/supported-commands

Overview of supported hash manipulation commands in Kvrocks.

```APIDOC
## Hash Commands

### Description
Commands for manipulating hash data structures.

### Commands
- **HDEL**: Deletes one or more fields from a hash.
- **HEXISTS**: Checks if a field exists in a hash.
- **HGET**: Retrieves the value associated with a field in a hash.
- **HGETALL**: Retrieves all fields and values in a hash.
- **HINCRBY**: Increments the integer value of a field in a hash.
- **HINCRBYFLOAT**: Increments the floating-point value of a field in a hash.
- **HKEYS**: Retrieves all the fields in a hash.
- **HLEN**: Returns the number of fields in a hash.
- **HMGET**: Retrieves the values associated with multiple fields in a hash.
- **HMSET**: Sets multiple fields in a hash to multiple values.
- **HRANGEBYLEX**: Returns elements in a sorted set within a specific range.
- **HSET**: Sets the value of a field in a hash.
- **HSETNX**: Sets the value of a field in a hash only if the field does not exist.
- **HSTRLEN**: Returns the length of string value for the specific field in a hash.
- **HVALS**: Returns all values stored in a hash.
- **HSCAN**: SCAN for fields of a hash.
- **HRANDFIELD**: Returns some random fields in a hash.
- **HSETEXPIRE**: Combination of HSET and EXPIRE.
```

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

### String Commands

Source: https://kvrocks.apache.org/docs/supported-commands

Overview of supported string manipulation commands in Kvrocks.

```APIDOC
## String Commands

### Description
Commands for manipulating string values stored in keys.

### Commands
- **APPEND**: Appends a value to a key's existing string value.
- **DECR**: Decrements the number stored at a key by one.
- **DECRBY**: Decrements the number stored at a key by a specified value.
- **GET**: Retrieves the value of a key.
- **GETEX**: Retrieves and optionally sets a new expiration for the value of a key.
- **GETRANGE**: Retrieves a substring from the string stored at a key.
- **SUBSTR**: Returns a substring of the value stored at a key.
- **GETSET**: Sets the value of a key and returns its old value.
- **INCR**: Increments the number stored at a key by one.
- **INCRBY**: Increments the number stored at a key by a specified value.
- **INCRBYFLOAT**: Increments the number stored at a key by a floating-point value.
- **MGET**: Retrieves the values of multiple keys.
- **MSET**: Sets multiple keys to multiple values.
- **MSETNX**: Sets multiple keys to multiple values only if none of the keys exist.
- **PSETEX**: Sets the value of a key and sets its expiration time in milliseconds.
- **SET**: Sets the value of a key.
- **SETEX**: Sets the value of a key and sets its expiration time in seconds.
- **SETNX**: Sets the value of a key only if the key does not already exist.
- **SETRANGE**: Overwrites part of a string at key starting at the specified offset.
- **STRLEN**: Returns the length of the string value stored at a key.
- **CAS**: Performs a Compare-And-Swap operation.
- **CAD**: Executes a Compare-And-Delete operation.
- **GETDEL**: Retrieves the value of a key and deletes the key afterward.
- **LCS**: Finds the longest common substring.
- **DIGEST**: Compute the hash digest of the string.
- **MSETEX**: Set multiple string keys atomically with expiration time.
- **DELEX**: Delete a string key if the condition is satisfied.
```

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

### Command Statistics Format

Source: https://kvrocks.apache.org/docs/info-sections

This format is used to display statistics for each command type, including calls, CPU time consumed, and average CPU time per command.

```text
cmdstat_XXX:calls=XXX,usec=XXX,usec_per_call=XXX  

```

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

### Download Grafana Dashboard JSON

Source: https://kvrocks.apache.org/docs/kvrocks-exporter

Use wget to download the official Kvrocks Grafana dashboard template for monitoring.

```bash
wget https://grafana.com/api/dashboards/15286 -O kvrocks-dashboard.json  
```

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

### Script Commands API

Source: https://kvrocks.apache.org/docs/supported-commands

APIs for executing and managing Lua scripts on the server.

```APIDOC
## EVAL /api/eval

### Description
Executes a Lua script server-side, accepting keys and arguments as parameters.

### Method
POST

### Endpoint
/api/eval

### Parameters
#### Request Body
- **script** (string) - Required - The Lua script to execute.
- **keys** (array) - Optional - An array of keys to be passed to the script.
- **args** (array) - Optional - An array of arguments to be passed to the script.

### Request Example
```json
{
  "script": "return redis.call('get', KEYS[1])",
  "keys": ["mykey"],
  "args": ["arg1"]
}
```

### Response
#### Success Response (200)
- **result** (any) - The result of the script execution.

#### Response Example
```json
{
  "result": "value"
}
```

## EVALSHA /api/evalsha

### Description
Executes a Lua script using its SHA1 hash, which is useful when the script is already cached on the server.

### Method
POST

### Endpoint
/api/evalsha

### Parameters
#### Request Body
- **sha1** (string) - Required - The SHA1 hash of the Lua script.
- **keys** (array) - Optional - An array of keys to be passed to the script.
- **args** (array) - Optional - An array of arguments to be passed to the script.

### Request Example
```json
{
  "sha1": "a1b2c3d4e5f67890a1b2c3d4e5f67890a1b2c3d4",
  "keys": ["mykey"],
  "args": ["arg1"]
}
```

### Response
#### Success Response (200)
- **result** (any) - The result of the script execution.

#### Response Example
```json
{
  "result": "value"
}
```

## EVAL_RO /api/eval_ro

### Description
Executes a Lua script server-side in read-only mode, allowing it in replica instances (similar to EVAL, but read-only).

### Method
POST

### Endpoint
/api/eval_ro

### Parameters
#### Request Body
- **script** (string) - Required - The Lua script to execute.
- **keys** (array) - Optional - An array of keys to be passed to the script.
- **args** (array) - Optional - An array of arguments to be passed to the script.

### Request Example
```json
{
  "script": "return redis.call('get', KEYS[1])",
  "keys": ["mykey"],
  "args": ["arg1"]
}
```

### Response
#### Success Response (200)
- **result** (any) - The result of the script execution.

#### Response Example
```json
{
  "result": "value"
}
```

## EVALSHA_RO /api/evalsha_ro

### Description
Executes a Lua script in read-only mode using its SHA1 hash (similar to EVALSHA, but read-only).

### Method
POST

### Endpoint
/api/evalsha_ro

### Parameters
#### Request Body
- **sha1** (string) - Required - The SHA1 hash of the Lua script.
- **keys** (array) - Optional - An array of keys to be passed to the script.
- **args** (array) - Optional - An array of arguments to be passed to the script.

### Request Example
```json
{
  "sha1": "a1b2c3d4e5f67890a1b2c3d4e5f67890a1b2c3d4",
  "keys": ["mykey"],
  "args": ["arg1"]
}
```

### Response
#### Success Response (200)
- **result** (any) - The result of the script execution.

#### Response Example
```json
{
  "result": "value"
}
```

## SCRIPT EXISTS /api/script/exists

### Description
Determines whether server-side Lua scripts exist in the script cache.

### Method
POST

### Endpoint
/api/script/exists

### Parameters
#### Request Body
- **sha1s** (array) - Required - An array of SHA1 hashes of the scripts to check.

### Request Example
```json
{
  "sha1s": ["a1b2c3d4e5f67890a1b2c3d4e5f67890a1b2c3d4"]
}
```

### Response
#### Success Response (200)
- **results** (array) - An array of booleans indicating whether each script exists.

#### Response Example
```json
{
  "results": [true]
}
```

## SCRIPT FLUSH /api/script/flush

### Description
Removes all server-side Lua scripts from the script cache.

### Method
POST

### Endpoint
/api/script/flush

### Response
#### Success Response (200)
- **message** (string) - Confirmation message.

#### Response Example
```json
{
  "message": "Script cache flushed successfully."
}
```

## SCRIPT LOAD /api/script/load

### Description
Loads a server-side Lua script to the script cache.

### Method
POST

### Endpoint
/api/script/load

### Parameters
#### Request Body
- **script** (string) - Required - The Lua script to load.

### Request Example
```json
{
  "script": "return 1"
}
```

### Response
#### Success Response (200)
- **sha1** (string) - The SHA1 hash of the loaded script.

#### Response Example
```json
{
  "sha1": "a1b2c3d4e5f67890a1b2c3d4e5f67890a1b2c3d4"
}
```
```

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

### INFO Command

Source: https://kvrocks.apache.org/docs/category/references

The INFO command retrieves comprehensive information and statistics about the Apache Kvrocks™ server. The output is designed to be easily parsed by machines and read by humans.

```APIDOC
## GET /info

### Description
Retrieves information and statistics about the Apache Kvrocks™ server.

### Method
GET

### Endpoint
/info

### Parameters
#### Query Parameters
- **section** (string) - Optional - Specifies which section of information to retrieve (e.g., 'server', 'clients', 'memory', 'persistence', 'stats', 'replication', 'cpu', 'commandstats', 'cluster', 'keyspace'). If not provided, all sections are returned.

### Response
#### Success Response (200)
- **info** (object) - An object containing various server statistics and information, categorized by section.

### Response Example
```json
{
  "info": {
    "server": {
      "version": "1.0.0",
      "process_id": 12345,
      "tcp_port": 6379
    },
    "clients": {
      "connected_clients": 10,
      "client_longest_output_list": 0,
      "blocked_clients": 0
    }
  }
}
```
```

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

### Perform a Search Query

Source: https://kvrocks.apache.org/docs/kvrocks-search

Use FT.SEARCH to perform a query on a given index. Supports returning specific fields, sorting, limiting results, and parameterized queries.

```redis-cli
FT.SEARCH index query 
  [RETURN count identifier [ identifier ...]] 
  [SORTBY sortby [ ASC | DESC]] 
  [LIMIT offset num] 
  [PARAMS nargs name value [ name value ...]]  
  [DIALECT 2]
```

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

### Pub/Sub Commands API

Source: https://kvrocks.apache.org/docs/supported-commands

APIs for publishing and subscribing to messages in real-time.

```APIDOC
## PSUBSCRIBE /api/psubscribe

### Description
Subscribes to channels using pattern matching. Receives messages sent to channels that match the pattern.

### Method
POST

### Endpoint
/api/psubscribe

### Parameters
#### Request Body
- **patterns** (array) - Required - An array of channel patterns to subscribe to.

### Request Example
```json
{
  "patterns": ["news.*", "updates.*"]
}
```

### Response
#### Success Response (200)
- **message** (string) - Confirmation of subscription.

#### Response Example
```json
{
  "message": "Subscribed to patterns: news.*, updates.*"
}
```

## PUBLISH /api/publish

### Description
Sends a message to a specific channel.

### Method
POST

### Endpoint
/api/publish

### Parameters
#### Request Body
- **channel** (string) - Required - The channel to publish the message to.
- **message** (string) - Required - The message to send.

### Request Example
```json
{
  "channel": "mychannel",
  "message": "Hello, world!"
}
```

### Response
#### Success Response (200)
- **recipients** (integer) - The number of clients that received the message.

#### Response Example
```json
{
  "recipients": 10
}
```

## MPUBLISH /api/mpublish

### Description
Publishes a message to multiple channels at once.

### Method
POST

### Endpoint
/api/mpublish

### Parameters
#### Request Body
- **channels** (array) - Required - An array of channels to publish the message to.
- **message** (string) - Required - The message to send.

### Request Example
```json
{
  "channels": ["channel1", "channel2"],
  "message": "Broadcast message"
}
```

### Response
#### Success Response (200)
- **recipients** (integer) - The total number of clients that received the message across all channels.

#### Response Example
```json
{
  "recipients": 25
}
```

## PUBSUB CHANNELS /api/pubsub/channels

### Description
Returns the active channels.

### Method
GET

### Endpoint
/api/pubsub/channels

### Response
#### Success Response (200)
- **channels** (array) - An array of active channel names.

#### Response Example
```json
{
  "channels": ["news.tech", "updates.general"]
}
```

## PUBSUB NUMPAT /api/pubsub/numpat

### Description
Returns a count of the unique pattern subscriptions.

### Method
GET

### Endpoint
/api/pubsub/numpat

### Response
#### Success Response (200)
- **count** (integer) - The number of unique pattern subscriptions.

#### Response Example
```json
{
  "count": 5
}
```

## PUBSUB NUMSUB /api/pubsub/numsub

### Description
Returns a count of subscribers to channels.

### Method
GET

### Endpoint
/api/pubsub/numsub

### Query Parameters
- **channels** (array) - Required - An array of channel names to get subscriber counts for.

### Response
#### Success Response (200)
- **subscribers** (object) - An object where keys are channel names and values are subscriber counts.

#### Response Example
```json
{
  "subscribers": {
    "channel1": 10,
    "channel2": 5
  }
}
```

## PUBSUB SHARDCHANNELS /api/pubsub/shardchannels

### Description
Returns the active shared channels.

### Method
GET

### Endpoint
/api/pubsub/shardchannels

### Response
#### Success Response (200)
- **shardChannels** (array) - An array of active shard channel names.

#### Response Example
```json
{
  "shardChannels": ["shard.news.tech", "shard.updates.general"]
}
```

## PUBSUB SHARDNUMSUB /api/pubsub/shardnumsub

### Description
Returns the count of subscribers of shard channels.

### Method
GET

### Endpoint
/api/pubsub/shardnumsub

### Query Parameters
- **shardChannels** (array) - Required - An array of shard channel names to get subscriber counts for.

### Response
#### Success Response (200)
- **shardSubscribers** (object) - An object where keys are shard channel names and values are subscriber counts.

#### Response Example
```json
{
  "shardSubscribers": {
    "shard.channel1": 8,
    "shard.channel2": 3
  }
}
```

## PUNSUBSCRIBE /api/punsubscribe

### Description
Unsubscribes from channels using pattern matching, stopping the receipt of messages.

### Method
POST

### Endpoint
/api/punsubscribe

### Parameters
#### Request Body
- **patterns** (array) - Optional - An array of channel patterns to unsubscribe from. If omitted, all subscriptions are cancelled.

### Request Example
```json
{
  "patterns": ["news.*"]
}
```

### Response
#### Success Response (200)
- **message** (string) - Confirmation of unsubscription.

#### Response Example
```json
{
  "message": "Unsubscribed from patterns: news.*"
}
```

## SUBSCRIBE /api/subscribe

### Description
Subscribes to a specific channel to receive messages sent to that channel.

### Method
POST

### Endpoint
/api/subscribe

### Parameters
#### Request Body
- **channels** (array) - Required - An array of channel names to subscribe to.

### Request Example
```json
{
  "channels": ["channel1", "channel2"]
}
```

### Response
#### Success Response (200)
- **message** (string) - Confirmation of subscription.

#### Response Example
```json
{
  "message": "Subscribed to channels: channel1, channel2"
}
```

## UNSUBSCRIBE /api/unsubscribe

### Description
Unsubscribes from one or more channels, stopping the receipt of messages.

### Method
POST

### Endpoint
/api/unsubscribe

### Parameters
#### Request Body
- **channels** (array) - Optional - An array of channel names to unsubscribe from. If omitted, all subscriptions are cancelled.

### Request Example
```json
{
  "channels": ["channel1"]
}
```

### Response
#### Success Response (200)
- **message** (string) - Confirmation of unsubscription.

#### Response Example
```json
{
  "message": "Unsubscribed from channels: channel1"
}
```

## SSUBSCRIBE /api/ssubscribe

### Description
Subscribes the client to the specified shard channels.

### Method
POST

### Endpoint
/api/ssubscribe

### Parameters
#### Request Body
- **shardChannels** (array) - Required - An array of shard channel names to subscribe to.

### Request Example
```json
{
  "shardChannels": ["shard.channel1", "shard.channel2"]
}
```

### Response
#### Success Response (200)
- **message** (string) - Confirmation of subscription.

#### Response Example
```json
{
  "message": "Subscribed to shard channels: shard.channel1, shard.channel2"
}
```

## SUNSUBSCRIBE /api/sunsubscribe

### Description
Unsubscribes the client from the specified shard channels.

### Method
POST

### Endpoint
/api/sunsubscribe

### Parameters
#### Request Body
- **shardChannels** (array) - Optional - An array of shard channel names to unsubscribe from. If omitted, all shard subscriptions are cancelled.

### Request Example
```json
{
  "shardChannels": ["shard.channel1"]
}
```

### Response
#### Success Response (200)
- **message** (string) - Confirmation of unsubscription.

#### Response Example
```json
{
  "message": "Unsubscribed from shard channels: shard.channel1"
}
```
```

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

### Control Kvrocks Memory Profiling with KPROFILE

Source: https://kvrocks.apache.org/docs/how-to-profile-memory

Use the KPROFILE command via redis-cli to manage memory profiling. Ensure Kvrocks is running with the correct environment variables set.

```redis-cli
KPROFILE MEMORY ENABLE
```

```redis-cli
KPROFILE MEMORY DUMP [dir]
```

```redis-cli
KPROFILE MEMORY DISABLE
```

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

### Key Management Commands

Source: https://kvrocks.apache.org/docs/supported-commands

Commands for managing keys, including deletion, expiration, and metadata introspection.

```APIDOC
## DEL

### Description
Deletes one or more keys.

### Method
COMMAND

### Endpoint
DEL key [key ...]

## EXISTS

### Description
Checks if a key exists.

### Method
COMMAND

### Endpoint
EXISTS key

## EXPIRE

### Description
Sets a key's time to live in seconds.

### Method
COMMAND

### Endpoint
EXPIRE key seconds
```

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

### Search Commands

Source: https://kvrocks.apache.org/docs/supported-commands

Full-text search capabilities provided by Kvrocks.

```APIDOC
## FT.SEARCH

### Description
Searches a full-text index for documents matching a query.

### Method
COMMAND

### Endpoint
FT.SEARCH [index] [query]
```

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

### Topology Management API

Source: https://kvrocks.apache.org/docs/cluster

Commands for setting and managing the Kvrocks cluster topology.

```APIDOC
## CLUSTERX SETNODES

### Description
Sets up the cluster topology by applying the entire topology information to all nodes. Nodes do not communicate with each other for this command.

### Method
COMMAND

### Endpoint
N/A (Command executed on Kvrocks node)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Command Syntax
`CLUSTERX SETNODES $ALL_NODES_INFO $VERSION $FORCE`

### Parameters Details
- **$ALL_NODES_INFO** (string) - Required - Cluster topology information. Format: `$node_id $ip $port $role $master_node_id $slot_range` (newline required between nodes).
  - `$node_id`: 40 chars string, unique ID in the cluster.
  - `$ip` and `$port`: Node IP address and listening port.
  - `$role`: Node's role (`master` or `slave`).
  - `$master_node_id`: Master node ID if role is `slave`; `-` if `master`.
  - `$slot_range`: Slots served by the current node (e.g., `0-100 200 205`).
- **$VERSION** (integer) - Required - Topology information version to control update order.
- **$FORCE** (0 or 1) - Optional - Force update topology information without verifying the version. Use when topology is broken.

### Request Example
```
CLUSTERX SETNODES "kvrockskvrockskvrockskvrockskvrocksnode1 10.32.68.251 6666 master - 0-5460 \n kvrockskvrockskvrockskvrockskvrocksnode2 10.32.68.250 6667 master - 5461-10992 \n kvrockskvrockskvrockskvrockskvrocksnode3 10.32.68.249 6666 master - 10993-16383" 1 0
```

### Response
#### Success Response (200)
(Command output indicating success or failure)

#### Response Example
(Example response depends on command execution)
```

```APIDOC
## CLUSTERX SETNODEID

### Description
Sets a unique 40-character node ID for the current Kvrocks instance.

### Method
COMMAND

### Endpoint
N/A (Command executed on Kvrocks node)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Command Syntax
`CLUSTERX SETNODEID $NODE_ID`

### Parameters Details
- **$NODE_ID** (string) - Required - A 40-character unique ID for the node within the cluster.

### Request Example
```
CLUSTERX SETNODEID kvrockskvrockskvrockskvrockskvrocksnode1
```

### Response
#### Success Response (200)
(Command output indicating success or failure)

#### Response Example
(Example response depends on command execution)
```

```APIDOC
## CLUSTERX VERSION

### Description
Inspects the current cluster topology information version.

### Method
COMMAND

### Endpoint
N/A (Command executed on Kvrocks node)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Command Syntax
`CLUSTERX VERSION`

### Request Example
```
CLUSTERX VERSION
```

### Response
#### Success Response (200)
- **version** (integer) - The current cluster topology version.

#### Response Example
```json
{
  "version": 1
}
```
```
Tokens:
Raw