redis-py

The Python response shape depends on both the protocol and the legacy_responses setting. Note that decode_responses is independent and still controls bulk-string decoding.

Redis provides two primary ways to listen for changes to keys using PubSub channels:

• Keyspace Notifications: Use the prefix __keyspace@<db>__:<keyname> to listen for operations performed on a specific key. The notification payload contains the operation performed (e.g., set, del).
• Keyevent Notifications: Use the prefix __keyevent@<db>:<event> to listen for specific operation events (e.g., __keyevent@0__:del). The notification payload contains the name of the impacted key.

Note: <db> refers to the database index (e.g., 0).

# Example Channel Names
# Keyspace: __keyspace@0__:mykey
# Keyevent: __keyevent@0__:del

By default, the SDK may return responses as strings. If you need to work with raw bytes or pass byte arguments to commands, configure the client with decode_responses=False. When this option is set, command responses are returned as bytes, and you can pass bytes instead of str for arguments like keys.

import redis
# Responses will be returned as bytes
client = redis.Redis(decode_responses=False)

# You can pass bytes as keys or arguments
client.set(b'my_key', b'my_value')
value = client.get(b'my_key')
assert isinstance(value, bytes)

In Redis Cluster, multi-key commands (like mset or mget) are only atomic if all keys map to the same hash slot. You can force keys into the same slot using hash tags (e.g., {foo}1 and {foo}2).

• Atomic operations: Use standard methods like mset() or mget(). If keys belong to different slots, a RedisClusterException will be raised.
• Non-atomic operations: Use mset_nonatomic() or mget_nonatomic(). The client will batch keys by their hash value and send separate commands to the respective slot owners. This allows operations across different slots but sacrifices atomicity.

# Atomic: requires hash tags to ensure same slot
rc.mset({'{foo}1': 'bar1', '{foo}2': 'bar2'})
rc.mget('{foo}1', '{foo}2')

# Non-atomic: works across different slots
rc.mset_nonatomic({'foo': 'value1', 'bar': 'value2', 'zzz': 'value3'})
rc.mget_nonatomic('foo', 'bar', 'zzz')

To perform fine-grained cache invalidation or react to partial object changes (like specific fields in a Hash), Redis supports subkey-aware notifications:

• Subkeyspace: Prefix __subkeyspace@<db>__:<keyname>. Payload format: <event>|<subkey_len>:<subkey>[,<subkey_len>:<subkey>...].
• Subkeyevent: Prefix __subkeyevent@<db>:<event>. Payload format: <key_len>:<key>|<subkey_len>:<subkey>[,<subkey_len>:<subkey>...].
• Subkeyspaceitem: Prefix __subkeyspaceitem@<db>__:<keyname>\n<subkey>. Payload format: <event>.
• Subkeyspaceevent: Prefix __subkeyspaceevent@<db>__:<event>|<keyname>. Payload format: A length-prefixed subkey list.

When creating a ClusterPubSub instance without specifying a node, the client transparently selects a node for the connection by hashing the requested channel name to find its keyslot.

Limitations: pattern subscribe and publish are currently not recommended because pattern matching (e.g., fo*) involves an unknown number of potential channel names that cannot be mapped to specific keyslots in advance.

# Connection is automatically set to the node holding the 'foo' keyslot
p1 = rc.pubsub()
p1.subscribe('foo')

# Manually specifying a node for PubSub
p2 = rc.pubsub(rc.get_node('localhost', 6379))

Commands are exposed through different client types (Standalone, Cluster, and Sentinel) and are organized by their functional area (Core, Module, Cluster, or Sentinel).

All command implementations eventually call the generic execute_command(*args, **kwargs) method. The SDK provides both synchronous and asynchronous versions of the API through method overloading.

The behavior of redis-py is determined by the combination of the wire protocol (protocol) and the response mode (legacy_responses).

Since release 6.0.0, redis-py defaults to DIALECT 2 for search and query commands (like FT.SEARCH and FT.AGGREGATE), automatically appending *DIALECT 2* to the command. This may impact result sets.

You can explicitly set a different dialect using the .dialect() method on a Query object.

from redis.commands.search.field import TextField
from redis.commands.search.query import Query
from redis.commands.search.index_definition import IndexDefinition
import redis

r = redis.Redis(host='localhost', port=6379, db=0)

# Query with default DIALECT 2
query = "@name: James Brown"
q = Query(query)
res = r.ft().search(q)

# Query with explicit DIALECT 1
query = "@name: James Brown"
q = Query(query).dialect(1)
res = r.ft().search(q)