Tutorial
How To Manage Hashes in Redis
Introduction
Redis is an open-source, in-memory key-value data store. A Redis hash is a data type that represents a mapping between a string field and a string value. Hashes can hold many field-value pairs and are designed to not take up much space, making them ideal for representing data objects. For example, a hash might represent a customer, and include fields like name
, address
, email
, or customer_id
.
This tutorial will go over how to manage hashes in Redis, from creating them to retrieving and deleting the data held within a hash.
How To Use This Guide
This guide is written as a cheat sheet with self-contained examples. We encourage you to jump to any section that is relevant to the task you’re trying to complete.
The commands shown in this guide were tested on an Ubuntu 18.04 server running Redis version 4.0.9. To set up a similar environment, you can follow Step 1 of our guide on How To Install and Secure Redis on Ubuntu 18.04. We will demonstrate how these commands behave by running them with redis-cli
, the Redis command line interface. Note that if you’re using a different Redis interface — Redli, for example — the exact output of certain commands may differ.
Alternatively, you could provision a managed Redis database instance to test these commands, but note that depending on the level of control allowed by your database provider, some commands in this guide may not work as described. To provision a DigitalOcean Managed Database, follow our Managed Databases product documentation. Then, you must either install Redli or set up a TLS tunnel in order to connect to the Managed Database over TLS.
Creating Hashes
To create a hash, run the hset
command. This command accepts the name of the hash key, the field string, and corresponding value string as arguments:
- hset poet:Verlaine nationality French
Note: In this example and the following ones, poet:Verlaine
is the hash key. Dots, dashes, and colons are commonly used to make multi-word keys and fields more readable. It’s helpful to make sure that your keys follow a consistent and easily readable format.
hset
returns (integer) 1
if the field specified is a new field and the value was set correctly:
Output(integer) 1
If, however, you fail to include a value, field, or name for the hash key, hset
will return an error.
Also, note that hset
will overwrite the contents of the hash if it already exists:
- hset poet:Verlaine nationality Francais
If the field already exists and its value was updated successfully, hset
will return (integer) 0
:
Output(integer) 0
You can also use hsetnx
to add fields to hashes, but it will only work if the field does not yet exist. If the specified field does already exist, the hsetnx
won’t have any effect and will return (integer) 0
:
- hsetnx poet:Verlaine nationality French
Output(integer) 0
To set multiple field/value pairs to a given set, use the hmset
command followed by the corresponding field/value strings:
- hmset poet:Verlaine born 1844 died 1896 genre Decadent
hmset
will just return OK
if it was successful.
Retrieving Information from Hashes
You can determine if a field exists for a given hash with the hexists
command:
- hexists poet:Verlaine nationality
hexists
will return (integer) 1
if the field does exist, and (integer) 0
if it doesn’t.
To return a field’s value, run the hget
command followed by the hash key and the field whose value you want to retrieve:
- hget poet:Verlaine nationality
Output"Francais"
hmget
uses the same syntax, but can return the values of multiple fields
- hmget poet:Verlaine born died
Output1) "1844"
2) "1896"
If the hash you pass to hget
or hmget
does not exist, both commands will return (nil)
:
- hmget poet:Dickinson born died
Output1) (nil)
2) (nil)
To obtain a list of all the fields held within a certain hash, run the hkeys
command:
- hkeys poet:Verlaine
Output1) "nationality"
2) "born"
3) "died"
4) "genre"
Conversely, run hvals
to retrieve a list of values held within a hash:
- hvals poet:Verlaine
Output1) "French"
2) "1844"
3) "1896"
4) "Decadent"
To return a list of every field held by a hash and their associated values, run hgetall
:
- hgetall poet:Verlaine
Output1) "nationality"
2) "French"
3) "born"
4) "1844"
5) "died"
6) "1896"
7) "genre"
8) "Decadent"
You can find the number of fields in a hash by running hlen
, which stands for “hash length”:
- hlen poet:Verlaine
Output(integer) 4
You can find the length of the value string associated with a field with hstrlen
, which stands for “hash string length”:
- hstrlen poet:Verlaine nationality
Output(integer) 8
hlen
will return (integer) 0
if the hash does not exist.
Removing Fields from Hashes
To delete a field from a hash, run the hdel
command. hdel
can accept multiple fields as arguments, and will return an integer indicating how many fields were removed from the hash:
- hdel poet:Verlaine born died
Output(integer) 2
If you pass a field that does not exist to hdel
, it will ignore that field but delete any other existing fields you specify.
Conclusion
This guide details a number of commands used to create and manage hashes in Redis. If there are other related commands, arguments, or procedures you’d like to see outlined in this guide, please ask or make suggestions in the comments below.
For more information on Redis commands, see our tutorial series on How to Manage a Redis Database.