{
  "schema_version": 2,
  "id": "operate/oss_and_stack/stack-with-enterprise/search/query-performance-factor",
  "title": "Configure the query performance factor for Redis Search in Redis Software",
  "url": "https://redis.io/docs/latest/operate/oss_and_stack/stack-with-enterprise/search/query-performance-factor/",
  "summary": "Configure the query performance factor for Redis Search in Redis Software to increase the performance of queries.",
  "aliases": [
    "/operate/oss_and_stack/stack-with-enterprise/search/scalable-search/",
    "/operate/oss_and_stack/stack-with-enterprise/search/query-performance-factor/"
  ],
  "tags": [
    "docs",
    "operate",
    "stack"
  ],
  "last_updated": "2026-10-02T14:53:57+01:00",
  "page_type": "content",
  "content_hash": "be059fd3c8dbab5c09ffaee5ef855cf1b74d5302c856764e23da7026bad6e6b9",
  "sections": [
    {
      "id": "overview",
      "title": "Overview",
      "role": "overview",
      "text": "Query performance factors are intended to increase the performance of queries, including [vector search](https://redis.io/docs/latest/develop/ai/search-and-query/query/vector-search). When enabled, it allows you to increase a database's compute capacity and query throughput by allocating more virtual CPUs per shard. This is in addition to horizontal scaling with more shards which enables a higher throughput of key value operations. This document describes how to configure the query performance factor.\n\n> [!NOTE]\n> Some use cases might not scale effectively. Redis experts can help determine if vertical scaling with Redis Search will boost performance for your use case and guide you on whether to use vertical scaling, horizontal scaling, or both."
    },
    {
      "id": "prerequisites",
      "title": "Prerequisites",
      "role": "content",
      "text": "Redis Search requires a cluster running Redis Software version 7.4.2-54 or later. For the simplified configuration experience (no shard restart required, new UI, and new REST API), Redis Software version 8.x or later is required.\n\nIf you do not have a cluster that supports Redis Search, [install Redis Software](https://redis.io/docs/latest/operate/rs/installing-upgrading/install/install-on-linux) version 7.4.2-54 or later on a new cluster, or [upgrade an existing cluster](https://redis.io/docs/latest/operate/rs/installing-upgrading/upgrading/upgrade-cluster)."
    },
    {
      "id": "sizing",
      "title": "Sizing",
      "role": "content",
      "text": "1. Calculate the hardware requirements for your Redis database:\n\n    1. Use the [hardware requirements documentation](https://redis.io/docs/latest/operate/rs/installing-upgrading/install/plan-deployment/hardware-requirements) to derive the overall cluster architecture.\n\n    1. Calculate the RAM requirements using the [Index Size Calculator](https://redis.io/redisearch-sizing-calculator/). The total RAM required is the sum of the dataset and index sizes.\n\n1. [Determine the query performance factor](#calculate-query-performance-factor) you want and the required number of CPUs. Unused CPUs, above the 20% necessary for Redis, can be used for the scalable Redis Search.\n\n1. Create a new Redis database with the number of CPUs configured for the query performance factor."
    },
    {
      "id": "calculate-query-performance-factor",
      "title": "Calculate query performance factor",
      "role": "content",
      "text": ""
    },
    {
      "id": "cpus-for-query-performance-factor",
      "title": "CPUs for query performance factor",
      "role": "content",
      "text": "Vertical scaling of Redis Search is achieved by provisioning additional CPUs for the RediSearch module. At least 20% of the available CPUs must be reserved for Redis internal processing. Use the following formula to define the maximum number of CPUs that can be allocated to search.\n\n| Variable | Value |\n|----------|-------|\n| CPUs per node | x |\n| Redis internals | 20% |\n| Available CPUs for Redis Search | floor(0.8 * x) |"
    },
    {
      "id": "query-performance-factor-versus-cpus",
      "title": "Query performance factor versus CPUs",
      "role": "content",
      "text": "The following table shows the number of CPUs required for each performance factor. This calculation is sensitive to how the search index and queries are defined. Certain scenarios might yield less throughput than the ratios in the following table.\n\n| Scale factor | Minimum CPUs required for Redis Search <WORKERS> |\n|----------------|-----------------------------------------|\n| None (default) | 1 |\n| 2 | 3 |\n| 4 | 6 |\n| 6 | 9 |\n| 8 | 12 |\n| 10 | 15 |\n| 12 | 18 |\n| 14 | 21 |\n| 16 | 24 |"
    },
    {
      "id": "example-performance-factor-calculation",
      "title": "Example performance factor calculation",
      "role": "example",
      "text": "| Variable | Value |\n|----------|-------|\n| CPUs per node | 8 |\n| Available CPUs | floor(0.8 * 8)=6 |\n| Scale factor | 4x |\n| Minimum CPUs required for scale factor - WORKERS | 6 |"
    },
    {
      "id": "configure-query-performance-factor-in-the-cluster-manager-ui",
      "title": "Configure query performance factor in the Cluster Manager UI",
      "role": "configuration",
      "text": ""
    },
    {
      "id": "config-db-ui-v8",
      "title": "Redis Software 8.x and later",
      "role": "content",
      "text": "Starting with Redis Software 8.x, configuring the query performance factor is simplified. You can select the query performance factor directly from the Cluster Manager UI without manually setting connection routing, connection limits, or module parameters. Changes to the query performance factor for existing databases take effect immediately without restarting shards.\n\nTo configure the query performance factor:\n\n1. In the Cluster Manager UI, [create a new database](https://redis.io/docs/latest/operate/rs/databases/create) or [edit an existing database](https://redis.io/docs/latest/operate/rs/databases/configure#edit-database-settings).\n\n1. In the **Capabilities** section, click **Add parameters**.\n\n    ![The Create database screen with the Add parameters button in the Capabilities section.](https://redis.io/docs/latest/images/rs/screenshots/databases/rs-qpf-add-parameters-v8.png)\n\n1. In the **Parameters** dialog, use the **Query performance factor** dropdown to select the performance factor value (Standard, 2x, 4x, 6x, 8x, 10x, 12x, 14x, or 16x).\n\n    ![The Parameters dialog with the Query performance factor dropdown showing available scaling options.](https://redis.io/docs/latest/images/rs/screenshots/databases/rs-qpf-select-factor-v8.png)\n\n1. Click **Done** to close the parameter editor.\n\n1. Click **Create** or **Save**.\n\nThe new configuration applies automatically. No shard restart is required, even for existing databases."
    },
    {
      "id": "config-db-ui-prior",
      "title": "Prior to Redis Software 8",
      "role": "content",
      "text": "To manually configure the query performance factor in Redis Software versions prior to 8.x:\n\n1. [Configure query performance factor parameters](#config-db-ui-params) when you create a new database or edit an existing database's configuration in the Cluster Manager UI.\n\n1. If you configure the query performance factor for an existing database, you also need to [restart shards](#restart-shards). Newly created databases can skip this step.\n\n#### Configure query performance factor parameters {#config-db-ui-params}\n\nYou can use the Cluster Manager UI to configure the query performance factor when you [create a new database](https://redis.io/docs/latest/operate/rs/databases/create) or [edit an existing database](https://redis.io/docs/latest/operate/rs/databases/configure#edit-database-settings) with search enabled.\n\n1. In the **Capabilities** section of the database configuration screen, click **Parameters**.\n\n1. If you are creating a new database, select **Search and query**.\n\n1. Adjust the **RediSearch** parameters to include: \n\n    `WORKERS <NUMBER_OF_THREADS>`\n\n    See [Calculate query performance factor](#calculate-query-performance-factor) to determine the minimum CPUs required to use for `<NUMBER_OF_THREADS>`.\n    \n1. Expand the **Query Performance Factor** section and enter the following values:\n\n    - `mnp` for **Connections routing**\n\n    - `32` for **Connections limit**\n\n    ![Configure search parameters and query performance factor.](https://redis.io/docs/latest/images/rs/screenshots/databases/rs-config-query-performance-factor.png)\n    \n1. Click **Done** to close the parameter editor.\n\n1. Click **Create** or **Save**.\n\n#### Restart shards {#restart-shards}\n\nAfter you update the query performance factor for an existing database, restart all shards to apply the new settings. You can migrate shards to restart them. Newly created databases can skip this step.\n\n1. Use [`rladmin status shards db <db-name>`](https://redis.io/docs/latest/operate/rs/references/cli-utilities/rladmin/status#status-shards) to list all shards for your database:\n\n    [code example]\n\n    Example output:\n\n    [code example]\n\n    Note the following fields for the next steps: \n    - `ID`: the Redis shard's ID.\n    - `NODE`: the node on which the shard currently resides.\n    - `ROLE`: `master` is a primary shard; `slave` is a replica shard.\n\n1. For each replica shard, use [`rladmin migrate shard`](https://redis.io/docs/latest/operate/rs/references/cli-utilities/rladmin/migrate) to move it to a different node and restart it:\n\n    [code example]\n\n1. After you migrate the replica shards, migrate the original primary shards.\n\n1. Rerun `rladmin status shards db <db-name>` to verify the shards migrated to different nodes:\n\n    [code example]\n\n    Example output:\n\n    [code example]"
    },
    {
      "id": "configure-query-performance-factor-with-the-rest-api",
      "title": "Configure query performance factor with the REST API",
      "role": "configuration",
      "text": ""
    },
    {
      "id": "rest-api-v8",
      "title": "Redis Software 8.x and later",
      "role": "content",
      "text": "Starting with Redis Software 8.x, you can configure the query performance factor using the [`query_performance_factor`](https://redis.io/docs/latest/operate/rs/references/rest-api/objects/bdb/query_performance_factor) object in the [BDB object](https://redis.io/docs/latest/operate/rs/references/rest-api/objects/bdb). You no longer need to manually set `sched_policy`, `conns`, or module `WORKERS` parameters. Changes take effect immediately without restarting shards.\n\n#### Create a new database {#create-db-rest-api-v8}\n\nTo create a database with the query performance factor enabled, use the [create database REST API endpoint](https://redis.io/docs/latest/operate/rs/references/rest-api/requests/bdbs#post-bdbs-v1) with the `query_performance_factor` field:\n\n[code example]\n\nThe following [cURL](https://curl.se/docs/) request creates a new database from the JSON example:\n\n[code example]\n\n#### Update an existing database {#update-db-rest-api-v8}\n\nTo configure the query performance factor for an existing database, use the [update database configuration](https://redis.io/docs/latest/operate/rs/references/rest-api/requests/bdbs#put-bdbs) endpoint with the `query_performance_factor` field:\n\n[code example]\n\nNo shard restart is required. The new configuration applies automatically.\n\n#### Query performance factor object fields\n\n| Field | Type/Value | Description |\n|-------|------------|-------------|\n| active | boolean (default:&nbsp;false) | If true, enables query performance factor for the database |\n| scaling_factor | integer (range:&nbsp;0-16) (default:&nbsp;0) | Scales the magnitude of the query performance factor |\n\nSee the [`query_performance_factor` object reference](https://redis.io/docs/latest/operate/rs/references/rest-api/objects/bdb/query_performance_factor) for more details."
    },
    {
      "id": "rest-api-prior",
      "title": "Prior to Redis Software 8",
      "role": "content",
      "text": "You can configure the query performance factor when you [create a new database](#create-db-rest-api) or [update an existing database](#update-db-rest-api) using the Redis Software [REST API](https://redis.io/docs/latest/operate/rs/references/rest-api).\n\n#### Create new database with the REST API {#create-db-rest-api}\n\nTo create a database and configure the query performance factor, use the [create database REST API endpoint](https://redis.io/docs/latest/operate/rs/references/rest-api/requests/bdbs#post-bdbs-v1) with a [BDB object](https://redis.io/docs/latest/operate/rs/references/rest-api/objects/bdb) that includes the following parameters:\n\n[code example]\n\nSee [Calculate performance factor](#calculate-query-performance-factor) to determine the value to use for `<NUMBER_OF_CPUS>`.\n\n##### Example REST API request for a new database\n\nThe following JSON is an example request body used to create a new database with a 4x query performance factor configured:\n\n[code example]\n\nThe following [cURL](https://curl.se/docs/) request creates a new database from the JSON example:\n\n[code example]\n\n#### Update existing database with the REST API {#update-db-rest-api}\n\nTo configure the query performance factor for an existing database, use the following REST API requests:\n\n- [Update database configuration](https://redis.io/docs/latest/operate/rs/references/rest-api/requests/bdbs#put-bdbs) to modify the DMC proxy.\n\n- [Upgrade module](https://redis.io/docs/latest/operate/rs/references/rest-api/requests/bdbs/modules/upgrade#post-bdb-modules-upgrade) to set the search module’s query performance factor.\n\n> [!NOTE]\n> - Because this procedure also restarts the database shards, you should perform it during a maintenance period.\n> - This procedure overwrites any existing module configuration parameters.\n\nThe following example script uses both endpoints to configure a 4x query performance factor:\n\n[code example]"
    },
    {
      "id": "monitoring-redis-search",
      "title": "Monitoring Redis Search",
      "role": "content",
      "text": "To monitor a database with a query performance factor configured:\n\n1. Integrate your Redis Software deployment with Prometheus. See [Prometheus and Grafana with Redis Software](https://redis.io/docs/latest/integrate/prometheus-with-redis-enterprise) for instructions.\n\n1. Monitor the `redis_process_cpu_usage_percent` shard metric.\n\n    The following Prometheus UI screenshot shows `redis_process_cpu_usage_percent` spikes for a database with two shards:\n\n    - 1st 100% spike: [`memtier_benchmark`](https://github.com/RedisLabs/memtier_benchmark) search test at the default (no additional CPUs for search).\n\n    - 2nd 100% spike: reconfiguration and shard restart for a 4x query performance factor.\n\n    - 3rd 600% spike: `memtier_benchmark` search test with threading at a 4x query performance factor (6 CPUs per shard).\n\n    ![The Prometheus graph shows three spikes for redis_process_cpu_usage_percent: 100%, another 100%, then 600%.](https://redis.io/docs/latest/images/rs/screenshots/monitor-rs-scalable-search-cpu-usage.png)"
    }
  ],
  "examples": [
    {
      "id": "config-db-ui-prior-ex0",
      "language": "sh",
      "code": "rladmin status shards db db-name",
      "section_id": "config-db-ui-prior"
    },
    {
      "id": "config-db-ui-prior-ex1",
      "language": "sh",
      "code": "SHARDS:\n    DB:ID   NAME                ID      NODE   ROLE   SLOTS   USED_MEMORY STATUS\n    db:2    db-name             redis:1 node:1 master 0-16383 1.95MB      OK    \n    db:2    db-name             redis:2 node:2 slave  0-16383 1.95MB      OK",
      "section_id": "config-db-ui-prior"
    },
    {
      "id": "config-db-ui-prior-ex2",
      "language": "sh",
      "code": "rladmin migrate shard <shard_id> target_node <node_id>",
      "section_id": "config-db-ui-prior"
    },
    {
      "id": "config-db-ui-prior-ex3",
      "language": "sh",
      "code": "rladmin status shards db db-name",
      "section_id": "config-db-ui-prior"
    },
    {
      "id": "config-db-ui-prior-ex4",
      "language": "sh",
      "code": "SHARDS:\n    DB:ID   NAME                ID      NODE   ROLE   SLOTS   USED_MEMORY STATUS\n    db:2    db-name             redis:1 node:2 master 0-16383 1.95MB      OK    \n    db:2    db-name             redis:2 node:1 slave  0-16383 1.95MB      OK",
      "section_id": "config-db-ui-prior"
    },
    {
      "id": "rest-api-v8-ex0",
      "language": "json",
      "code": "{\n    \"name\": \"scalable-search-db\",\n    \"type\": \"redis\",\n    \"memory_size\": 10000000,\n    \"port\": 13000,\n    \"authentication_redis_pass\": \"<your default db pwd>\",\n    \"proxy_policy\": \"all-master-shards\",\n    \"sharding\": true,\n    \"shards_count\": 3,\n    \"shards_placement\": \"sparse\",\n    \"shard_key_regex\": [{\"regex\": \".*\\\\{(?<tag>.*)\\\\}.*\"}, {\"regex\": \"(?<tag>.*)\"}],\n    \"replication\": false,\n    \"module_list\": [{\n        \"module_name\": \"search\",\n        \"module_args\": \"\"\n    }],\n    \"query_performance_factor\": {\n        \"active\": true,\n        \"scaling_factor\": 4\n    }\n}",
      "section_id": "rest-api-v8"
    },
    {
      "id": "rest-api-v8-ex1",
      "language": "sh",
      "code": "curl -k -u \"<user>:<password>\" https://<host>:9443/v1/bdbs -H \"Content-Type:application/json\" -d @scalable-search-db.json",
      "section_id": "rest-api-v8"
    },
    {
      "id": "rest-api-v8-ex2",
      "language": "sh",
      "code": "curl -k -u \"<user>:<password>\" -X PUT https://<host>:9443/v1/bdbs/<DB_ID> -H \"Content-Type:application/json\" -d '{\n    \"query_performance_factor\": {\n        \"active\": true,\n        \"scaling_factor\": 4\n    }\n}'",
      "section_id": "rest-api-v8"
    },
    {
      "id": "rest-api-prior-ex0",
      "language": "json",
      "code": "{\n    \"sched_policy\": \"mnp\",\n    \"conns\": 32,\n    \"module_list\": [{\n        \"module_name\": \"search\",\n        \"module_args\": \"WORKERS <NUMBER_OF_THREADS>\"\n    }]\n}",
      "section_id": "rest-api-prior"
    },
    {
      "id": "rest-api-prior-ex1",
      "language": "json",
      "code": "{\n    \"name\": \"scalable-search-db\",\n    \"type\": \"redis\",\n    \"memory_size\": 10000000,\n    \"port\": 13000,\n    \"authentication_redis_pass\": \"<your default db pwd>\",\n    \"proxy_policy\": \"all-master-shards\",\n    \"sched_policy\": \"mnp\",\n    \"conns\": 32,\n    \"sharding\": true,\n    \"shards_count\": 3,\n    \"shards_placement\": \"sparse\",\n    \"shard_key_regex\": [{\"regex\": \".*\\\\{(?<tag>.*)\\\\}.*\"}, {\"regex\": \"(?<tag>.*)\"}],\n    \"replication\": false,\n    \"module_list\": [{\n        \"module_name\": \"search\",\n        \"module_args\": \"WORKERS 6\"\n    }]\n}",
      "section_id": "rest-api-prior"
    },
    {
      "id": "rest-api-prior-ex2",
      "language": "sh",
      "code": "curl -k -u \"<user>:<password>\" https://<host>:9443/v1/bdbs -H \"Content-Type:application/json\" -d @scalable-search-db.json",
      "section_id": "rest-api-prior"
    },
    {
      "id": "rest-api-prior-ex3",
      "language": "sh",
      "code": "#!/bin/bash\nexport DB_ID=1\nexport CPU=6\nexport MODULE_ID=`curl -s -k -u \"<user>:<password>\" https://<host>:9443/v1/bdbs/$DB_ID | jq '.module_list[] | select(.module_name==\"search\").module_id' | tr -d '\"'`\n\ncurl -o /dev/null -s -k -u \"<user>:<password>\" -X PUT https://<host>:9443/v1/bdbs/$DB_ID -H \"Content-Type:application/json\" -d '{\n    \"sched_policy\": \"mnp\",\n    \"conns\": 32\n}'\n\nsleep 1\n\ncurl -o /dev/null -s -k -u \"<user>:<password>\" https://<host>:9443/v1/bdbs/$DB_ID/modules/upgrade -H \"Content-Type:application/json\" -d '{\n    \"modules\": [\n      {\n        \"module_name\": \"search\",\n        \"new_module_args\": \"WORKERS '$CPU'\",\n        \"current_module\": \"'$MODULE_ID'\",\n        \"new_module\": \"'$MODULE_ID'\"\n      }\n    ]\n}'",
      "section_id": "rest-api-prior"
    }
  ]
}