{
  "id": "quickstart",
  "title": "RedisGears Python quick start",
  "url": "https://redis.io/docs/latest/operate/oss_and_stack/stack-with-enterprise/gears-v1/python/quickstart/",
  "summary": "A quick start to learn how to use RedisGears with Python.",
  "tags": [
    "docs",
    "operate",
    "stack"
  ],
  "last_updated": "2026-04-01T08:10:08-05:00",
  "page_type": "content",
  "content_hash": "8422ac88954ce07448af64ae2a5bd8c3dc44dafa660f6ad192bb47eedb2910d3",
  "sections": [
    {
      "id": "overview",
      "title": "Overview",
      "role": "overview",
      "text": "For this tutorial, you need:\n\n- Either:\n    - A Redis Software cluster with the [RedisGears module and Python plugin installed]() and [enabled on a database]()\n    - A Redis Open Source database with the RedisGears module\n- `redis-cli` with connectivity to a Redis database"
    },
    {
      "id": "redisgears-basics",
      "title": "RedisGears basics",
      "role": "content",
      "text": "In this quick start guide, we'll see how to use RedisGears to perform batch processing and event processing.\n\nWith RedisGears, **batch processing** means processing the data already stored in a Redis database. **Event processing** means processing changes to the Redis key space.\n\nThe examples below assume an empty Redis database."
    },
    {
      "id": "batch-processing",
      "title": "Batch processing",
      "role": "content",
      "text": "Let's start with the simplest example. From the `redis-cli`, run the following command:\n\n[code example]\n\nThis command doesn't do much; it simply iterates over the keyspace. Let's add a key and run it again:\n\n[code example]\n\nWe've added a single string, and you can see that this gears function processes it, even though it does nothing with the data. Let's actually do something with the data. So first, we'll add a few more strings:\n\n[code example]\n\nWe now have three strings in our database. Suppose we want to perform a unique word count on these strings. We can write a RedisGears function to do this just that. So open a file called `wordcount.py`, and add the following code:\n\n[code example]\n\nThere are two ways to load files into RedisGears. For production deployments, we recommend using the special [`gears-cli`](https://github.com/gears-project/gears-cli). However, for the purpose of this demonstration, the easiest way is to pass the filename through the `redis-cli` command, like so:\n\n[code example]\n\nThe results here show the number of occurrences of each word in all of our strings. So, we've effectively processed the data in our Redis database all at once, in a batch."
    },
    {
      "id": "event-processing",
      "title": "Event processing",
      "role": "content",
      "text": "You may have noticed that all of the RedisGears functions above end with a call to `run()`. This indicates that the function should be run immediately on the data in the Redis database. But what if you want to process data as it arrives in Redis? In that case, your functions will end with a call to `register()`, which will store the function and apply it as events occur in Redis.\n\nLet's see how to register a function. First, suppose we're writing hashes to our database that represent users. They take the following form:\n\n[code example]\n\nEach hash has two fields, one containing a name and the other an age. Now, suppose we want to keep a record of the maximum age of all users. We can register a RedisGears function to do this. Open up a file called `maxage.py`, and add the following code:\n\n[code example]\n\nYou can see here that we define two methods: `age()` and `compare_and_swap()`. Even if you're not familiar with Python, you should be able to see what the methods do.\n\nBelow the method definitions is the RedisGears data flow that we're defining. Notice that at the end we call `register()` to register the function to listen for events.\n\nTo load this function into RedisGears, run the following:\n\n[code example]\n\nNow start the `redis-cli`, and create a couple of hashes:\n\n[code example]\n\nTo see if the RedisGears function is working, check the value of `age:maximum`:\n\n[code example]"
    },
    {
      "id": "next-steps",
      "title": "Next steps",
      "role": "content",
      "text": "You should now have a basic idea of how to run RedisGears functions for batch and event processing. If you're interested in write-behind caching, see our [write-behind caching]() overview."
    }
  ],
  "examples": [
    {
      "id": "batch-processing-ex0",
      "language": "sh",
      "code": "redis.cloud:6379> RG.PYEXECUTE \"GearsBuilder().run()\"\n1) (empty array)\n2) (empty array)",
      "section_id": "batch-processing"
    },
    {
      "id": "batch-processing-ex1",
      "language": "sh",
      "code": "redis.cloud:6379> SET message \"hello world\"\nOK\nredis.cloud:6379> RG.PYEXECUTE \"GearsBuilder().run()\"\n1) 1) \"{'event': None, 'key': 'message', 'type': 'string', 'value': 'hello world'}\"\n2) (empty array)",
      "section_id": "batch-processing"
    },
    {
      "id": "batch-processing-ex2",
      "language": "sh",
      "code": "redis.cloud::6379> SET message:2 \"hello galaxy\"\nOK\nredis.cloud:6379> SET message:3 \"hello universe\"\nOK",
      "section_id": "batch-processing"
    },
    {
      "id": "batch-processing-ex3",
      "language": "py",
      "code": "gb = GearsBuilder()\ngb.map(lambda x: x['value'])     # map each key object to its string value\ngb.flatmap(lambda x: x.split())  # split each string into a list of words\ngb.countby()                     # run a count-unique on these words\ngb.run()",
      "section_id": "batch-processing"
    },
    {
      "id": "batch-processing-ex4",
      "language": "sh",
      "code": "$ redis-cli rg.pyexecute \"`cat wordcount.py`\"\n1) 1) \"{'key': 'world', 'value': 1}\"\n   2) \"{'key': 'galaxy', 'value': 1}\"\n   3) \"{'key': 'hello', 'value': 3}\"\n   4) \"{'key': 'universe', 'value': 1}\"\n2) (empty array)",
      "section_id": "batch-processing"
    },
    {
      "id": "event-processing-ex0",
      "language": "sh",
      "code": "redis.cloud:6379> HSET person:3 name \"Summer Smith\" age 17\n(integer) 2\nredis.cloud:6379> HSET person:4 name \"James Jameson\" age 21\n(integer) 2",
      "section_id": "event-processing"
    },
    {
      "id": "event-processing-ex1",
      "language": "py",
      "code": "def age(x):\n  ''' Extracts the age from a person's record '''\n  return int(x['value']['age'])\n\ndef compare_and_swap(x):\n  ''' Checks and sets the current maximum '''\n  k = 'age:maximum'\n  v = execute('GET', k)   # read key's current value\n  v = int(v) if v else 0  # initialize to 0 if None\n  if x > v:               # if a new maximum found\n    execute('SET', k, x)  # set key to new value\n\n# Event handling function registration\ngb = GearsBuilder()\ngb.map(age) # Extract the 'age' field from each hash\ngb.foreach(compare_and_swap) # Compare the max age to the value stored at age:maximum\ngb.register(prefix='person:*') # Only process keys matching the pattern 'person:*'",
      "section_id": "event-processing"
    },
    {
      "id": "event-processing-ex2",
      "language": "sh",
      "code": "$ redis-cli RG.PYEXECUTE \"`cat maxage.py`\"",
      "section_id": "event-processing"
    },
    {
      "id": "event-processing-ex3",
      "language": "sh",
      "code": "redis.cloud:6379> HSET person:5 name \"Marek Michalski\" age 17\n(integer) 2\nredis.cloud:6379> HSET person:6 name \"Noya Beit\" age 21\n(integer) 2",
      "section_id": "event-processing"
    },
    {
      "id": "event-processing-ex4",
      "language": "sh",
      "code": "redis.cloud:6379> GET age:maximum\n\"21\"",
      "section_id": "event-processing"
    }
  ]
}