{
  "schema_version": 2,
  "id": "commands/hrandfield",
  "title": "HRANDFIELD",
  "url": "https://redis.io/docs/latest/commands/hrandfield/",
  "summary": "Returns one or more random fields from a hash.",
  "since": "6.2.0",
  "tags": [
    "docs",
    "develop",
    "stack",
    "oss",
    "rs",
    "rc",
    "oss",
    "kubernetes",
    "clients"
  ],
  "last_updated": "2026-09-18T09:47:41+01:00",
  "page_type": "content",
  "content_hash": "c6291f2681dded7c085db10ed1905b6d04f98bf79556ba4af16224847ea358e4",
  "sections": [
    {
      "id": "overview",
      "title": "Overview",
      "role": "overview",
      "text": "When called with just the `key` argument, return a random field from the hash value stored at `key`.\n\nIf the provided `count` argument is positive, return an array of **distinct fields**.\nThe array's length is either `count` or the hash's number of fields ([`HLEN`](https://redis.io/docs/latest/commands/hlen)), whichever is lower.\n\nIf called with a negative `count`, the behavior changes and the command is allowed to return the **same field multiple times**.\nIn this case, the number of returned fields is the absolute value of the specified `count`.\n\nThe optional `WITHVALUES` modifier changes the reply so it includes the respective values of the randomly selected hash fields."
    },
    {
      "id": "required-arguments",
      "title": "Required arguments",
      "role": "content",
      "text": "<details open><summary><code>key</code></summary>\n\nThe name of the key that holds the hash.\n\n</details>"
    },
    {
      "id": "optional-arguments",
      "title": "Optional arguments",
      "role": "parameters",
      "text": "<details open><summary><code>count</code></summary>\n\nThe number of fields to return. A positive `count` returns up to that many distinct fields; a negative `count` returns exactly `|count|` fields and may repeat fields. When omitted, a single random field is returned.\n\n</details>\n\n<details open><summary><code>WITHVALUES</code></summary>\n\nAlso return the value of each selected field. Can only be used together with `count`.\n\n</details>"
    },
    {
      "id": "examples",
      "title": "Examples",
      "role": "example",
      "text": "redis> HSET coin heads obverse tails reverse edge null\n(integer) 3\nredis> HRANDFIELD coin\nredis> HRANDFIELD coin\nredis> HRANDFIELD coin -5 WITHVALUES"
    },
    {
      "id": "specification-of-the-behavior-when-count-is-passed",
      "title": "Specification of the behavior when count is passed",
      "role": "content",
      "text": "When the `count` argument is a positive value this command behaves as follows:\n\n* No repeated fields are returned.\n* If `count` is bigger than the number of fields in the hash, the command will only return the whole hash without additional fields.\n* The order of fields in the reply is not truly random, so it is up to the client to shuffle them if needed.\n\nWhen the `count` is a negative value, the behavior changes as follows:\n\n* Repeating fields are possible.\n* Exactly `count` fields, or an empty array if the hash is empty (non-existing key), are always returned.\n* The order of fields in the reply is truly random."
    },
    {
      "id": "redis-software-and-redis-cloud-compatibility",
      "title": "Redis Software and Redis Cloud compatibility",
      "role": "content",
      "text": "| Redis<br />Software | Redis<br />Cloud | <span style=\"min-width: 9em; display: table-cell\">Notes</span> |\n|:----------------------|:-----------------|:------|\n| <span title=\"Supported\">&#x2705; Standard</span><br /><span title=\"Supported\"><nobr>&#x2705; Active-Active</nobr></span> | <span title=\"Supported\">&#x2705; Standard</span><br /><span title=\"Supported\"><nobr>&#x2705; Active-Active</nobr></span> |  |"
    },
    {
      "id": "return-information",
      "title": "Return information",
      "role": "returns",
      "text": "**RESP2:**\n\nAny of the following:\n* [Nil reply](../../develop/reference/protocol-spec#bulk-strings): if the key doesn't exist\n* [Bulk string reply](../../develop/reference/protocol-spec#bulk-strings): a single, randomly selected field when the `count` option is not used\n* [Array reply](../../develop/reference/protocol-spec#arrays): a list containing `count` fields when the `count` option is used, or an empty array if the key does not exists.\n* [Array reply](../../develop/reference/protocol-spec#arrays): a list of fields and their values when `count` and `WITHVALUES` were both used.\n\n**RESP3:**\n\nAny of the following:\n* [Null reply](../../develop/reference/protocol-spec#nulls): if the key doesn't exist\n* [Bulk string reply](../../develop/reference/protocol-spec#bulk-strings): a single, randomly selected field when the `count` option is not used\n* [Array reply](../../develop/reference/protocol-spec#arrays): a list containing `count` fields when the `count` option is used, or an empty array if the key does not exists.\n* [Array reply](../../develop/reference/protocol-spec#arrays): a list of fields and their values when `count` and `WITHVALUES` were both used."
    }
  ],
  "examples": []
}