You can enter multiple credit cards and set one of them as the default one. The
payments will be charged from the default credit card.
## Payment Security
Upstash does not store users' credit card information in its servers. We use
Stripe Inc payment processing company to handle payments. You can read more
about payment security in Stripe
[here](https://stripe.com/docs/security/stripe).
# Audit Logs
Source: https://upstash.com/docs/common/account/auditlogs
Audit logs give you a chronological set of activity records that have affected
your databases and Upstash account. You can see the list of all activities on a
single page. You can access your audit logs under `Account > Audit Logs` in your
console:
Here the `Source` column shows if the action has been called by the console or via
an API key. The `Entity` column gives you the name of the resource that has been
affected by the action. For example, when you delete a database, the name of the
database will be shown here. Also, you can see the IP address which performed the
action.
## Security
You can track your audit logs to detect any unusual activity on your account and
databases. When you suspect any security breach, you should delete the API key
related to suspicious activity and inform us by emailing
[support@upstash.com](mailto:support@upstash.com)
## Retention period
After the retention period, the audit logs are deleted. The retention period for free databases is 7 days, for pay-as-you-go databases, it is 30 days, and for the Pro tier, it is one year.
# AWS Marketplace
Source: https://upstash.com/docs/common/account/awsmarketplace
Once you click subscribe, you will be prompted to select which personal or team account you wish to link with your AWS Subscription.
Once your account is linked, regardless of which Upstash product you use, all of your usage will be billed to your AWS Account. You can also upgrade or downgrade your subscription through Upstash console.
# Cost Explorer
Source: https://upstash.com/docs/common/account/costexplorer
The Cost Explorer pages allow you to view your current and previous monthsā costs. To access the Cost Explorer, navigate to the left menu and select Account > Cost Explorer. Below is an example report:
You can select a specific month to view the cost breakdown for that period. Here's the explanation of the fields in the report:
**Request:** This represents the total number of requests sent to the database.
**Storage:** This indicates the average size of the total storage consumed. Upstash database includes a persistence layer for data durability. For example, if you have 1 GB of data in your database throughout the entire month, this value will be 1 GB. Even if your database is empty for the first 29 days of the month and then expands to 30 GB on the last day, this value will still be 1 GB.
**Cost:** This field represents the total cost of your database in US Dollars.
> The values for the current month is updated hourly, so values can be stale up
> to 1 hour.
# Create an Account
Source: https://upstash.com/docs/common/account/createaccount
You can sign up for 
You can download receipt. If one of your payments failed, you can retry your
payment on this page.
# Teams and Users
Source: https://upstash.com/docs/common/account/teams
Team management enables collaboration with other users. You can create a team and invite people to join by using their email addresses. Team members will have access to databases created under the team based on their assigned roles.
## Create Team
You can create a team using the menu `Account > Teams`
> A user can create up to 5 teams. You can be part of even more teams but only
> be the owner of 5 teams. If you need to own more teams please email us at
> [support@upstash.com](mailto:support@upstash.com).
You can still continue using your personal account or switch to a team.
> The databases in your personal account are not shared with anyone. If you want
> your database to be accessible by other users, you need to create it under a
> team.
## Switch Team
You need to switch to the team to create databases shared with other team
members. You can switch to the team via the switch button in the team table. Or
you can click your profile pic in the top right and switch to any team listed
there.
## Add/Remove Team Member
After switching to a team, if you are the Owner or an Admin of the team, you can add team members by navigating to `Account > Teams`. Simply enter their email addresses.It's not an issue if the email addresses are not yet registered with Upstash. Once the user registers with that email, they will gain access to the team. We do not send invitations; when you add a member, they become a member directly. You can also remove members from the same page.
> Only Admins or the Owner can add/remove users.
## Roles
While adding a team member, you will need to select a role. Here are the access rights associated with each role:
* Admin: This role has full access, including the ability to add and remove members, manage databases, and payment methods.
* Dev: This role can create, manage, and delete databases but cannot manage users or payment methods.
* Finance: This role is limited to managing payment methods and cannot manage databases or users.
* Owner: The Owner role has all the access rights of an Admin and, in addition to having the ability to delete the team. This role is automatically assigned to the user who created the team, and you cannot assign it to other members.
> If you want to change a user's role, you will need to delete and re-add them with the desired access rights.
## Delete Team
Only the original creator (owner) can delete a team. Also the team should not
have any active databases, namely all databases under the team should be deleted
first. To delete your team, first you need to switch your personal account then
you can delete your team in the team list under `Account > Teams`.
### SDKs for Popular Languages
To enhance the developer experience, Upstash is developing SDKs in various popular programming languages. These SDKs simplify the process of integrating Upstash services with your applications by providing straightforward methods and functions that abstract the underlying REST API calls.
### Resources
[Redis REST API Docs](https://upstash.com/docs/redis/features/restapi)
[QStash REST API Docs](https://upstash.com/docs/qstash/api/authentication)
[Redis SDK - Typescript](https://github.com/upstash/upstash-redis)
[Redis SDK - Python](https://github.com/upstash/redis-python)
[QStash SDK - Typescript](https://github.com/upstash/sdk-qstash-ts)
# Global Replication
Source: https://upstash.com/docs/common/concepts/global-replication
Global Replication for Low Latency and High Availability
Upstash Redis automatically replicates your data to the regions you choose, so your application stays fast and responsive-no matter where your users are.
Add or remove regions from a database at any time with zero downtime. Each region acts as a replica, holding a copy of your data for low latency and high availability.
***
## Built for Modern Serverless Architectures
In serverless computing, performance isn't just about fast codeāit's also about fast, reliable data access from anywhere in the world. Whether you're using Vercel Functions, Cloudflare Workers, Fastly Compute, or Deno Deploy, your data layer needs to be as distributed and flexible as your compute for best performance.
Upstash Global replicates your Redis data across multiple regions to:
* Minimize round-trip latency
* Guarantee high availability at scale
...even under heavy or dynamic workloads. Our HTTP-based RedisĀ® client is optimized for serverless environments and delivers consistent performance under high concurrency or variable workloads.
As serverless platforms evolve with features like in-function concurrency (e.g. [Vercel's Fluid Compute](https://vercel.com/fluid)), you need a data layer that can keep up. Upstash Redis is a globally distributed, low-latency database that scales with your compute, wherever it runs.
***
## How Global Replication Works
To minimize latency for read operations, we use a replica model. Our tests show sub-millisecond latency for read commands in the same AWS region as the Upstash RedisĀ® instance.
**Read commands are automatically served from the geographically closest replica**:
**Write commands go to the primary database** for consistency. After a successful write, they are replicated to all read replicas:
***
## Available Regions
To create a globally distributed database, select a primary region and the number of read regions:
* Select a primary region for most write operations for best performance.
* Select read regions close to your users for optimized read speeds.
Each request is then automatically served by the closest read replica for maximum performance and minimum latency:
**You can create read replicas in the following regions:**
* AWS US-East-1 (North Virginia)
* AWS US-East-2 (Ohio)
* AWS US-West-1 (North California)
* AWS US-West-2 (Oregon)
* AWS EU-West-1 (Ireland)
* AWS EU-West-2 (London)
* AWS EU-Central-1 (Frankfurt)
* AWS AP-South-1 (Mumbai)
* AWS AP-Northeast-1 (Tokyo)
* AWS AP-Southeast-1 (Singapore)
* AWS AP-Southeast-2 (Sydney)
* AWS SA-East-1 (SĆ£o Paulo)
Check out [our blog post](https://upstash.com/blog/global-database) to learn more about our global replication philosophy. You can also explore our [live benchmark](https://latency.upstash.com/) to see Upstash Redis latency from different locations around the world.
# Scale to Zero
Source: https://upstash.com/docs/common/concepts/scale-to-zero
Only pay for what you really use.
Traditionally, cloud services required users to predict their resource needs and provision servers or instances based on those predictions. This often led to over-provisioning to handle potential peak loads, resulting in paying for unused resources during periods of low demand.
By *scaling to zero*, our pricing model aligns more closely with actual usage.
## Pay for usage
You're only charged for the resources you actively use. When your application experiences low activity or no incoming requests, the system automatically scales down resources to a minimal level. This means you're no longer paying for idle capacity, resulting in cost savings.
## Flexibility
"Scaling to zero" offers flexibility in scaling both up and down. As your application experiences traffic spikes, the system scales up resources to meet demand. Conversely, during quiet periods, resources scale down.
## Focus on Innovation
Developers can concentrate on building and improving the application without constantly worrying about resource optimization. Upstash handles the scaling, allowing developers to focus on creating features that enhance user experiences.
In essence, this aligns pricing with actual utilization, increases cost efficiency, and promotes a more sustainable approach to resource consumption. This model empowers businesses to leverage cloud resources without incurring unnecessary expenses, making cloud computing more accessible and attractive to a broader range of organizations.
# Serverless
Source: https://upstash.com/docs/common/concepts/serverless
What do we mean by serverless?
Upstash is a modern serverless data platform. But what do we mean by serverless?
## No Server Management
In a serverless setup, developers don't need to worry about configuring or managing servers. We take care of server provisioning, scaling, and maintenance.
## Automatic Scaling
As traffic or demand increases, Upstash automatically scales the required resources to handle the load. This means applications can handle sudden spikes in traffic without manual intervention.
## Granular Billing
We charge based on the actual usage of resources rather than pre-allocated capacity. This can lead to more cost-effective solutions, as users only pay for what they consume. [Read more](/common/concepts/scale-to-zero)
## Stateless Functions
In serverless architectures, functions are typically stateless. However, the traditional approach involves establishing long-lived connections to databases, which can lead to issues in serverless environments if connections aren't properly managed after use. Additionally, there are scenarios where TCP connections may not be feasible. Upstash addresses this issue by offering access via HTTP, a universally available protocol across all platforms.
## Rapid Deployment
Fast iteration is the key to success in today's competitive environment. You can create a new Upstash database in seconds, with minimal required configuration.
# Account & Teams
Source: https://upstash.com/docs/common/help/account
## Create an Account
You can sign up to 
3. Enter a name for your key. You can not use the same name for multiple keys.
You need to download or copy/save your API key. Upstash does not remember or
keep your API for security reasons. So if you forget your API key, it becomes
useless; you need to create a new one.
You can create multiple keys. It is recommended to use different keys in different applications. By default one user can create up to 37 API keys. If you need more than that, please send us an email at [support@upstash.com](mailto:support@upstash.com) ### Deleting an API key When an API key is exposed (e.g. accidentally shared in a public repository) or not being used anymore; you should delete it. You can delete the API keys in `Account > API Keys` screen. ### Roadmap **Role based access:** You will be able to create API keys with specific privileges. For example you will be able to create a key with read-only access. **Stats:** We will provide reports based on usage of your API keys. # null Source: https://upstash.com/docs/devops/developer-api/redis/autoscaling # Create Backup Source: https://upstash.com/docs/devops/developer-api/redis/backup/create_backup POST https://api.upstash.com/v2/redis/create-backup/{id} This endpoint creates a backup for a Redis database. ## URL Parameters
**Options:** `admin`, `dev` or `finance`
To view a more detailed Next.js quick start guide for setting up QStash, refer to the [quick start](/qstash/quickstarts/vercel-nextjs) guide.
It's also possible to schedule a background job to run at a later time using [schedules](/qstash/features/schedules).
If you'd like to invoke another endpoint when the background job is complete, you can use [callbacks](/qstash/features/callbacks).
# Batching
Source: https://upstash.com/docs/qstash/features/batch
[Publishing](/qstash/howto/publishing) is great for sending one message
at a time, but sometimes you want to send a batch of messages at once.
This can be useful to send messages to a single or multiple destinations.
QStash provides the `batch` endpoint to help
you with this.
If the format of the messages are valid, the response will be an array of
responses for each message in the batch. When batching URL Groups, the response
will be an array of responses for each destination in the URL Group. If one
message fails to be sent, that message will have an error response, but the
other messages will still be sent.
1. You publish a message to QStash using the `/v2/publish` endpoint
2. QStash will enqueue the message and deliver it to the destination
3. QStash waits for the response from the destination
4. When the response is ready, QStash calls your callback URL with the response
Callbacks publish a new message with the response to the callback URL. Messages
created by callbacks are charged as any other message.
## How do I use Callbacks?
You can add a callback url in the `Upstash-Callback` header when publishing a
message. The value must be a valid URL.
1. **Retry** - Republish the message and remove it from the dead letter queue. Republished messages are just like any other message and will be retried automatically if they fail.
2. **Delete** - Delete the message from the dead letter queue.
## Limitations
Dead letter queues are limited to a certain number of messages. If you exceed this limit, the oldest messages will be dropped.
Unhandled messages are evicted after some time.
See the [pricing](https://upstash.com/pricing/qstash) page for more information.
# Flow Control
Source: https://upstash.com/docs/qstash/features/flowcontrol
FlowControl enables you to limit the number of messages sent to your endpoint via delaying the delivery.
There are two limits that you can set with the FlowControl feature: [Rate](#rate-limit) and [Parallelism](#parallelism-limit).
And if needed both parameters can be [combined](#rate-and-parallelism-together).
For the `FlowControl`, you need to choose a key first. This key is used to count the number of calls made to your endpoint.
There are not limits to number of keys you can use.
Send this token along with every request made to `QStash` inside the
`Authorization` header like this:
```
"Authorization": "Bearer 
Either you or a previously setup schedule will create a message.
When a message is ready for execution, it will be become `ACTIVE` and a delivery to
your API is attempted.
If you API responds with a status code between `200 - 299`, the task is
considered successful and will be marked as `DELIVERED`.
Otherwise the message is being retried if there are any retries left and moves to `RETRY`. If all retries are exhausted, the task has `FAILED` and the message will be moved to the DLQ.
During all this a message can be cancelled via [DELETE /v2/messages/:messageId](https://docs.upstash.com/qstash/api/messages/cancel). When the request is received, `CANCEL_REQUESTED` will be logged first.
If retries are not exhausted yet, in the next deliver time, the message will be marked as `CANCELLED` and will be completely removed from the system.
## Console
Head over to the [Upstash Console](https://console.upstash.com/qstash) and go to
the `Logs` tab, where you can see the latest status of your messages.
# Delete Schedules
Source: https://upstash.com/docs/qstash/howto/delete-schedule
Deleting schedules can be done using the [schedules api](/qstash/api/schedules/remove).
# Local Development
Source: https://upstash.com/docs/qstash/howto/local-development
QStash requires a publicly available API to send messages to.
During development when applications are not yet deployed, developers typically need to expose their local API by creating a public tunnel.
While local tunneling works seamlessly, it requires code changes between development and production environments and increase friction for developers.
To simplify the development process, Upstash provides QStash CLI, which allows you to run a development server locally for testing and development.
It works!
", }, }); ``` In the `body` field, specify any parameters supported by [the Resend Send Email API](https://resend.com/docs/api-reference/emails/send-email), such as `from`, `to`, `subject`, and `html`. ## Sending Batch Emails To send multiple emails at once, use Resendās [Batch Email API](https://resend.com/docs/api-reference/emails/send-batch-emails). Set the `batch` option to `true` to enable batch sending. Each email configuration is defined as an object within the `body` array. ```typescript await client.publishJSON({ api: { name: "email", provider: resend({ token: "It works!
", }, { from: "AcmeIt works!
", }, ], }); ``` Each entry in the `body` array represents an individual email, allowing customization of `from`, `to`, `subject`, `html`, and any other Resend-supported fields. # Development Server License Agreement Source: https://upstash.com/docs/qstash/misc/license ## 1. Purpose and Scope This software is a development server implementation of QStash API ("Development Server") provided for testing and development purposes only. It is not intended for production use, commercial deployment, or as a replacement for the official QStash service. ## 2. Usage Restrictions By using this Development Server, you agree to the following restrictions: a) The Development Server may only be used for: * Local development and testing * Continuous Integration (CI) testing * Educational purposes * API integration development b) The Development Server may NOT be used for: * Production environments * Commercial service offerings * Public-facing applications * Operating as a Software-as-a-Service (SaaS) * Reselling or redistributing as a service ## 3. Restrictions on Modification and Reverse Engineering You may not: * Decompile, reverse engineer, disassemble, or attempt to derive the source code of the Development Server * Modify, adapt, translate, or create derivative works based upon the Development Server * Remove, obscure, or alter any proprietary rights notices within the Development Server * Attempt to bypass or circumvent any technical limitations or security measures in the Development Server ## 4. Technical Limitations Users acknowledge that the Development Server: * Operates entirely in-memory without persistence * Provides limited functionality compared to the official service * Offers no data backup or recovery mechanisms * Has no security guarantees * May have performance limitations * Does not implement all features of the official service ## 5. Warranty Disclaimer THE DEVELOPMENT SERVER IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED. THE AUTHORS OR COPYRIGHT HOLDERS SHALL NOT BE LIABLE FOR ANY CLAIMS, DAMAGES, OR OTHER LIABILITY ARISING FROM THE USE OF THE SOFTWARE IN VIOLATION OF THIS LICENSE. ## 6. Termination Your rights under this license will terminate automatically if you fail to comply with any of its terms. Upon termination, you must cease all use of the Development Server. ## 7. Acknowledgment By using the Development Server, you acknowledge that you have read this license, understand it, and agree to be bound by its terms. # API Examples Source: https://upstash.com/docs/qstash/overall/apiexamples ### Use QStash via: * cURL * [Typescript SDK](https://github.com/upstash/sdk-qstash-ts) * [Python SDK](https://github.com/upstash/qstash-python) Below are some examples to get you started. You can also check the [how to](/qstash/howto/publishing) section for more technical details or the [API reference](/qstash/api/messages) to test the API. ### Publish a message to an endpoint Simple example to [publish](/qstash/howto/publishing) a message to an endpoint.
### Publish a message
A message can be any shape or form: json, xml, binary, anything, that can be
transmitted in the http request body. We do not impose any restrictions other
than a size limit of 1 MB (which can be customized at your request).
In addition to the request body itself, you can also send HTTP headers. Learn
more about this in the [message publishing section](/qstash/howto/publishing).
### Check Message Status
Head over to [Upstash Console](https://console.upstash.com/qstash) and go to the
`Logs` tab where you can see your message activities.
Learn more about different states [here](/qstash/howto/debug-logs).
## Features and Use Cases
The URL you use to invoke your function typically follows this format, especially if you follow the same stack configuration as shown above:
`https://
and make these two variables available to your Lambda in your function configuration:
Tada, we just deployed a live Lambda with the AWS CDK! š
### Manual Deployment
1. Create a new Lambda function by going to the [AWS dashboard](https://us-east-1.console.aws.amazon.com/lambda/home?region=us-east-1#/create/function) for your desired lambda region. Give your new function a name and select `Node.js 20.x` as runtime, then create the function.
2. To make this Lambda available under a public URL, navigate to the `Configuration` tab and click `Function URL`:
3. In the following dialog, you'll be asked to select one of two authentication types. Select `NONE`, because we are handling authentication ourselves. Then, click `Save`.
You'll see the function URL on the right side of your function overview:
4. Get your current and next signing key from the
[Upstash Console](https://console.upstash.com/qstash).
5. Still under the `Configuration` tab, set the `QSTASH_CURRENT_SIGNING_KEY` and `QSTASH_NEXT_SIGNING_KEY`
environment variables:
6. Add the following script to your `package.json` file to build and zip your code:
```json package.json
{
"scripts": {
"build": "rm -rf ./dist; esbuild index.ts --bundle --minify --sourcemap --platform=node --target=es2020 --outfile=dist/index.js && cd dist && zip -r index.zip index.js*"
}
}
```
7. Click the `Upload from` button for your Lambda and
deploy the code to AWS. Select `./dist/index.zip` as the upload file.
Tada, you've manually deployed a zip file to AWS Lambda! š
## Testing the Integration
To make sure everything works as expected, navigate to your QStash request builder and send a request to your freshly deployed Lambda function:
Alternatively, you can also send a request via CURL:
```bash Terminal
curl --request POST "https://qstash.upstash.io/v2/publish/
Afterwards we will add a public URL to this lambda by going to the
`Configuration` tab:
Select `Auth Type = NONE` because we are handling authentication ourselves.
After creating the url, you should see it on the right side of the overview of
your function:
### 5. Set Environment Variables
Get your current and next signing key from the
[Upstash Console](https://console.upstash.com/qstash)
On the same `Configuration` tab from earlier, we will now set the required
environment variables:
### 6. Deploy your Lambda function
We need to bundle our code and zip it to deploy it to AWS.
Add the following script to your `Makefile` file (or corresponding pipenv
script):
```yaml
zip:
rm -rf dist
pip3 install --target ./dist pyjwt
cp lambda_function.py ./dist/lambda_function.py
cd dist && zip -r lambda.zip .
mv ./dist/lambda.zip ./
```
When calling `make zip` this will install PyJwt and zip the code.
Afterwards we can click the `Upload from` button in the lower right corner and
deploy the code to AWS. Select `lambda.zip` as upload file.
### 7. Publish a message
Open a different terminal and publish a message to QStash. Note the destination
url is the URL from step 4.
```bash
curl --request POST "https://qstash.upstash.io/v2/publish/https://urzdbfn4et56vzeasu3fpcynym0zerme.lambda-url.eu-west-1.on.aws" \
-H "Authorization: Bearer 
Clicking on the application will direct you to the application details page, where you can perform the integration process. Switch to the **Settings** tab in the application details, and proceed to **Integrations** section. You will see various Worker integrations listed. To proceed, click the **Add Integration** button associated with the QStash.
On the Integration page, connect to your Upstash account. Then, select the related database from the dropdown menu. Finalize the process by pressing Save button.
#### Setting up Manually
Navigate to [Upstash Console](https://console.upstash.com) and copy/paste your QStash credentials to `wrangler.toml` as below.
```yaml
[vars]
QSTASH_URL="REPLACE_HERE"
QSTASH_TOKEN="REPLACE_HERE"
QSTASH_CURRENT_SIGNING_KEY="REPLACE_HERE"
QSTASH_NEXT_SIGNING_KEY="REPLACE_HERE"
```
### Test and Deploy
You can test the function locally with `npx wrangler dev`
Deploy your function to Cloudflare with `npx wrangler deploy`
The endpoint of the function will be provided to you, once the deployment is done.
### Publish a message
Open a different terminal and publish a message to QStash. Note the destination
url is the same that was printed in the previous deploy step.
```bash
curl --request POST "https://qstash.upstash.io/v2/publish/https://cloudflare-workers.upstash.workers.dev" \
-H "Authorization: Bearer 
Once you start the schedule, QStash will invoke the endpoint at the specified time. You can
scroll down and verify the job has been created!
You can also head over to [Upstash Console](https://console.upstash.com/qstash) and go to the
`Logs` tab where you can see your message activities.
Loading...
}
{msg && {msg}
}
We can also view the logs on Vercel and QStash
QStash
Loading...
}
{msg && {msg}
}Hello World
", content_type="text/html", ) ``` #### Publish a message with [content-based-deduplication](/qstash/features/deduplication) ```python from qstash import QStash client = QStash("Hello World
", headers: { "Content-Type": "text/html", }, }); ``` #### Publish a message with [content-based-deduplication](/qstash/features/deduplication) ```typescript import { Client } from "@upstash/qstash"; const client = new Client({ token: "
* Or for an existing database by clicking Enable in the Configuration/Auto Upgrade box in the database details page:
# Backup/Restore
Source: https://upstash.com/docs/redis/features/backup
You can create a manual backup of your database and restore that backup to any of your databases. Both backup and restore operations require that your database is in one of the AWS regions.
Additionally, you can utilize the daily backup feature to automatically create backups of your database on a daily basis.
### Create A Manual Backup
To create a manual backup of your database:
* Go to the database details page and navigate to the `Backups` tab
* Click on the `Backup` button and fill in a name for your backup. **Your backup name must be unique.**
* Then click on the `Create` button.
During the process of creating a backup for your database, it is important to note that your database will be temporarily locked, which means these operations will be unavailable during this time:
* Create Database Backup
* Enable TLS
* Move Database to Team
* Restore Database Backup
* Update Eviction
* Update Password
* Delete Database
### Restore A Backup
To restore a backup that was created from your current database, follow the steps below:
* Go to the database details page and navigate to the `Backups` tab
* Click on the `Restore` button next to the backup record listed.
* Click on `Restore`. **Be aware of the fact that your target database will be flushed with this operation.**
### Restore A Backup From Another Database
To restore a backup that was created from one of your databases other than the current one, follow the steps below:
* Go to the database details page and navigate to the `Backups` tab
* Click on the `Restore...` button
* Select the source database, referring to the database from which the backup was generated.
* Select the backup record that you want to restore to the current database.
* Click on `Start Restore`. **Be aware of the fact that your target database will be flushed with this operation.**
### Enable Daily Automated Backup
To enable daily automated backup for your database:
* Go to the database details page and navigate to the `Backups` tab
* Enable the switch next to the `Daily Backup`
* Click on `Enable`
### Disable Daily Automated Backup
To disable the daily automated backup for your database, please follow the steps below:
* Go to the database details page and navigate to the `Backups` tab
* Disable the switch next to the `Daily Backup`
* Click on `Disable`
# Consistency
Source: https://upstash.com/docs/redis/features/consistency
Upstash utilizes a leader-based replication mechanism. Under this mechanism,
each key is assigned to a leader replica, which is responsible for handling
write operations on that key. The remaining replicas serve as backups to the
leader. When a write operation is performed on a key, it is initially processed
by the leader replica and then asynchronously propagated to the backup replicas.
This ensures that data consistency is maintained across the replicas. Reads can
be performed from any replica.
Each replica employs a failure detector to track liveness of the leader replica.
When the leader replica fails for a reason, remaining replicas start a new
leader election round and elect a new leader. This is the only unavailability
window for the cluster where *write* your requests can be blocked for a short
period of time. Also in case of cluster wide failures like network partitioning
(split brain); periodically running anti entropy jobs resolve the conflicts
using `Last-Writer-Wins` algorithm and converge the replicas to the same state.
This model gives a better write consistency and read scalability but can provide
only **Eventual Consistency**. Additionally you can achieve **Causal
Consistency** (`Read-Your-Writes`, `Monotonic-Reads`, `Monotonic-Writes` and
`Writes-Follow-Reads` guarantees) for a single Redis connection. (A TCP
connection forms a session between client and server).
Checkout [Read Your Writes](/redis/howto/readyourwrites) for more details on how to achieve RYW consistency.
Checkout [Replication](/redis/features/replication) for more details on Replication mechanism.
* Or for an existing database by clicking **Enable** in Configuration/Eviction
box in the database details page:
Upstash currently uses a single eviction algorithm, called
**optimistic-volatile**, which is a combination of *volatile-random* and
*allkeys-random* eviction policies available in
[the original Redis](https://redis.io/docs/manual/eviction/#eviction-policies).
Initially, Upstash employs random sampling to select keys for eviction, giving
priority to keys marked with a TTL (expire field). If there is a shortage of
volatile keys or they are insufficient to create space, additional non-volatile
keys are randomly chosen for eviction. In future releases, Upstash plans to
introduce more eviction policies, offering users a wider range of options to
customize the eviction behavior according to their specific needs.
# Global Database
Source: https://upstash.com/docs/redis/features/globaldatabase
In the global database, the replicas are distributed across multiple regions
around the world. The clients are routed to the nearest region. This helps with
minimizing latency for use cases where users can be anywhere in the world.
### Primary Region and Read Regions
The Upstash Global database is structured with a Primary Region and multiple
Read Regions. When a write command is issued, it is initially sent and processed
at the Primary Region. The write operation is then replicated to all the Read
Regions, ensuring data consistency across the database.
On the other hand, when a read command is executed, it is directed to the
nearest Read Region to optimize response time. By leveraging the Global
database's distributed architecture, read operations can be performed with
reduced latency, as data retrieval occurs from the closest available Read
Region.
The Global database's design thus aids in minimizing read operation latency by
efficiently distributing data across multiple regions and enabling requests to
be processed from the nearest Read Region.
User selects a single primary region and multiple read regions. For the best
performance, you should select the primary region in the same location where
your writes happen. Select the read regions where your clients that read the
Redis located. You may have your database with a single primary region but no
read regions which would be practically same with a single region (regional)
database. You can add or remove regions on a running Redis database.
Here the list of regions currently supported:
* AWS US-East-1 North Virginia
* AWS US-East-2 Ohio
* AWS US-West-1 North California
* AWS US-West-2 Oregon
* AWS EU-West-1 Ireland
* AWS EU-West-2 London
* AWS EU-Central-1 Frankfurt
* AWS AP-South-1 Mumbai
* AWS AP-SouthEast-1 Singapore
* AWS AP-SouthEast-2 Sydney
* AWS AP-NorthEast-1 Japan
* AWS SA-East-1 SĆ£o Paulo
In our internal tests, we see the following latencies (99th percentile):
* Read latency from the same region \<1ms
* Write latency from the same region \<5ms
* Read/write latency from the same continent \<50ms
### Architecture
In the multi region architecture, each key is owned by a primary replica which
is located at the region that you choose as primary region. Read replicas become
the backups of the primary for the related keys. The primary replica processes
the writes, then propagates them to the read replicas. Read requests are
processed by all replicas, this means you can read a value from any of the
replicas. This model gives a better write consistency and read scalability.
Each replica employs a failure detector to track the liveness of the primary
replica. When the primary replica fails for a reason, read replicas start a new
leader election round and elect a new leader (primary). This is the only
unavailability window for the cluster where your requests can be blocked for a
short period of time.
If the user doesn't exist or password doesn't match then an error will be
returned.
```shell
redis-cli> ACL RESTTOKEN upstash fakepass
(error) ERR Wrong password or user "upstash" does not exist
```
## Redis Protocol vs REST API
### REST API Pros
* If you want to access to Upstash database from an environment like CloudFlare
Workers, WebAssembly, Fastly Compute\@Edge then you can not use Redis protocol
as it is based on TCP. You can use REST API in those environments.
* REST API is request (HTTP) based where Redis protocol is connection based. If
you are running serverless functions (AWS Lambda etc), you may need to manage
the Redis client's connections. REST API does not have such an issue.
* Redis protocol requires Redis clients. On the other hand, REST API is
accessible with any HTTP client.
### Redis Protocol Pros
* If you have legacy code that relies on Redis clients, the Redis protocol
allows you to utilize Upstash without requiring any modifications to your
code.
* By leveraging the Redis protocol, you can take advantage of the extensive
Redis ecosystem. For instance, you can seamlessly integrate your Upstash
database as a session cache for your Express application.
## REST API vs GraphQL API
The REST API generally exhibits lower latency compared to the GraphQL API. In
the case of the REST API, direct access to the database is established. However,
with the GraphQL API, a proxy layer is present, responsible for accepting
connections and translating GraphQL queries into the Redis protocol.
## Introduction
In this guideline we will outline the steps to integrate Upstash into your platform (GUI or Web App) and allow your users to create and manage Upstash databases without leaving your interfaces. We will explain how to use OAuth2.0 as the underlying foundation to enable this access seamlessly.
If your product or service offering utilizes Redis, Vector or QStash or if there is a common use case that your end users enable by leveraging these database resources, we invite you to be a partner with us. By integrating Upstash into your platform, you can offer a more complete package for your customers and become a one stop shop. This will also position yourself at the forefront of innovative cloud computing trends such as serverless and expand your customer base.
This is the most commonly used partnership integration model that can be easily implemented by following this guideline. Recently [Cloudflare workers integration](https://blog.cloudflare.com/cloudflare-workers-database-integration-with-upstash/) is implemented through this methodology. For any further questions or partnership discussions please send us an email at [partnerships@upstash.com](mailto:partnerships@upstash.com)
1. User clicksĀ **`Connect Upstash`**Ā button from web app.
2. Web app initiates Upstash OAuth 2.0 flow and it can useĀ **[Auth0 native libraries](https://auth0.com/docs/libraries)**.
3. App will open new browser:
```
https://auth.upstash.com/authorize?response_type=code&audience=upstash-api&scope=offline_access&client_id=XXXXXXXXXX&redirect_uri=http%3A%2F%2Flocalhost:3000
```
The information required for Redis clients is displayed here as **Endpoint**,
**Port** and **Password**. Also when you click on `Clipboard` button on **Connect to your database** section, you can copy
the code that is required for your client.
Below, we will provide examples from popular Redis clients, but the information above should help you configure all Redis clients similarly.
Enter a name for your function and select `Node.js 14.x` as runtime. Click
`Create Function`.
Now you are on the function screen, scroll below to `Function Code` section. On
`Code entry type` selection, select `Upload a .zip file`. Upload the `app.zip`
file you have just created and click on the `Save` button on the top-right. You
need to see your code as below:
Now you can test your code. Click on the `Test` button on the top right. Create
an event like the below:
```
{
"key": "foo",
"value": "bar"
}
```
Now, click on Test. You will see something like this:
Congratulations, now your lambda function inserts entry to your Upstash
database.
**What can be the next?**
* You can write and deploy another function to just get values from the
database.
* You can learn better ways to deploy your functions such as
[serverless framework](https://serverless.com/) and
[AWS SAM](https://aws.amazon.com/serverless/sam/)
* You can integrate
[API Gateway](https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-create-api-as-simple-proxy-for-lambda.html)
so you can call your function via http.
* You can learn about how to monitor your functions from CloudWatch as described
[here](https://docs.aws.amazon.com/lambda/latest/dg//monitoring-functions-logs.html)
.
#### Redis Connections in AWS Lambda
Although Redis connections are very lightweight, a new connection inside each
Lambda function can cause a notable latency. On the other hand, reusing Redis
connections inside the AWS Lambda functions has its own drawbacks. When AWS
scales out Lambda functions, the number of open connections can rapidly
increase. Fortunately, Upstash detects and terminates the idle and zombie
connections thanks to its smart connection handling algorithm. Since this
algorithm is used; we have been recommending caching your Redis connection in
serverless functions.
# Import/Export Data
Source: https://upstash.com/docs/redis/howto/importexport
## Using Upstash Console
You can use the migration wizard in the
[Upstash console](https://console.upstash.com) to import your Redis to Upstash.
In the database list page, click on the `Import` button, you will see the dialog
like below:
You can move your data from either an Upstash database or a database in another
provider (or on premise).
In this chart, all your databases are listed. You can click on the name of the
database that you want to see detailed information. Also, the following
information is listed for each database:
* The region of the database
* The current size of the data
* The current count of active connections: Not that if your connections are
short-lived then you may see 0 here most of the time.
## Database Detail
The charts on this page show metrics that are specific to the selected database.
### Current Month
* This chart shows the daily cost of the database. The chart covers the last 5
days.
### Daily Request
This chart shows the daily total number of requests to the database. The chart
covers the last 5 days.
### Throughput
Throughput chart shows throughput values for reads, writes and commands (all
commands including reads and writes) per second. The chart covers the last 1
hour and it is updated every 10 seconds.
### Service Time Latency
This chart shows the processing time of the request between it is received by
the server and the response is sent to the caller. It shows the times in max,
mean, min, 99.9 percentile and 99.99 percentile. The chart covers the last 1
hour and it is updated every 10 seconds.
### Data Size
This chart shows the data size of your database. The chart covers the last 24
hours and it is updated every 10 seconds.
### Connections
This chart shows the number of active client connections. It shows the number of
open connections plus the number of short-lived connections that started and
terminated in 10 seconds period. The chart covers the last 1 hour and it is
updated every 10 seconds.
### Key Space
This chart shows the number of keys. The chart covers the last 24 hours and it
is updated every 10 seconds.
### Hits / Misses
This chart shows the number of hits per second and misses per second. The chart
covers the last 1 hour and it is updated every 10 seconds.
# Migrate Regional to Global Database
Source: https://upstash.com/docs/redis/howto/migratefromregionaltoglobal
This guide will help you migrate your data from a regional Upstash Redis database to a global database.
If your database is Upstash Regional, we strongly recommend you to migrate to [Upstash Redis Global](https://upstash.com/docs/common/concepts/global-replication).
Our Regional Redis databases are legacy and deprecated.
## Why Migrate?
* New infrastructure, more modern and more secure
* Upstash Global is SOC-2 and HIPAA compatible
* Enhanced feature set: New features are only made available on Upstash Global
* Ability to add/remove read regions on the go
* Better performance as per our benchmarks
## Prerequisites
Before starting the migration, make sure you have:
1. An existing regional Upstash Redis database (source)
2. A new global Upstash Redis database (destination)
3. Access to both databases' credentials (connection strings, passwords)
## Migration Process
There are several official ways to migrate your data:
If you do not have a Redis database or Vector Index yet, you can create one
from the dropdown menu.
Once you have selected all resources, click the `Create` button at the bottom of
the page.
After all environment variables are created, you will be forwarded to Vercel. Go
to your project settings where you can see all added environment variables.
Depending on the resources you selected, you will see something similar to this:
You need to redeploy your app for the environment variable to be used.
### Create Your Redis Client
If you completed the integration steps above and redeploy your app, the added
environment variables will be accessible inside your Vercel application. You can
now use them in your clients to connect
#### Redis
```ts
const { Redis } = require("@upstash/redis");
module.exports = async (req, res) => {
/**
* Redis.fromEnv() will read the following from environment variables:
* - UPSTASH_REDIS_REST_URL
* - UPSTASH_REDIS_REST_TOKEN
*/
const redis = Redis.fromEnv();
await redis.set("foo", "bar");
const bar = await redis.get("foo");
res.json({
body: `foo: ${bar}`,
});
};
```
#### QStash
**Client**
```ts
import { Client } from "@upstash/qstash";
const c = new Client({
token: process.env.QSTASH_TOKEN,
});
const res = await c.publishJSON({
url: "https://my-api...",
body: {
hello: "world",
},
});
```
**Receiver**
```ts
import { Receiver } from "@upstash/qstash";
const r = new Receiver({
currentSigningKey: process.env.QSTASH_CURRENT_SIGNING_KEY,
nextSigningKey: process.env.QSTASH_NEXT_SIGNING_KEY,
});
const isValid = await r.verify(
signature: "..."
body: "..."
})
```
### Managing your Integrations
The [Integration Dashboard](https://console.upstash.com/integration/vercel)
allows you to see all your integrations, link new projects or manage existing
ones.
### Support
If you have any issue you can ask in our
[Discord server](https://discord.gg/w9SenAtbme) or send email at
[support@upstash.com](mailto:support@upstash.com)
# BullMQ with Upstash Redis
Source: https://upstash.com/docs/redis/integrations/bullmq
You can use BullMQ and Bull with Upstash Redis. BullMQ is a Node.js queue library that is built on top of Bull. It is a Redis-based queue library so you can use Upstash Redis as its storage.
## Install
```bash
npm install bullmq upstash-redis
```
## Usage
```javascript
import { Queue } from 'bullmq';
const myQueue = new Queue('foo', { connection: {
host: "UPSTASH_REDIS_ENDPOINT",
port: 6379,
password: "UPSTASH_REDIS_PASSWORD",
tls: {}
}});
async function addJobs() {
await myQueue.add('myJobName', { foo: 'bar' });
await myQueue.add('myJobName', { qux: 'baz' });
}
await addJobs();
```
## Billing Optimization
BullMQ accesses Redis regularly, even when there is no queue activity. This can incur extra costs because Upstash charges per request on the Pay-As-You-Go plan. With the introduction of [our Fixed plans](https://upstash.com/docs/redis/overall/pricing#all-plans-and-limits), **we recommend switching to a Fixed plan to avoid increased command count and high costs in BullMQ use cases.**
# Celery with Upstash Redis
Source: https://upstash.com/docs/redis/integrations/celery
You can use **Celery** with Upstash Redis to build scalable and serverless task queues. Celery is a Python library that manages asynchronous task execution, while Upstash Redis acts as both the broker (queue) and the result backend.
## Setup
### Install Celery
To get started, install the necessary libraries using `pip`:
```bash
pip install "celery[redis]"
```
### Database Setup
Create a Redis database using the [Upstash Console](https://console.upstash.com). Export the `UPSTASH_REDIS_HOST`, `UPSTASH_REDIS_PORT`, and `UPSTASH_REDIS_PASSWORD` to your environment:
```bash
export UPSTASH_REDIS_HOST=
2. Note down your `
* **Claude**: Navigate to `Settings > Developer` and click `Edit Config`. This will open the `claude_desktop_config.json` file. [Refer to the MCP documentation for more details](https://modelcontextprotocol.io/quickstart/user).
* **Copilot**: Create a `.vscode/mcp.json` file in your workspace directory. For Copilot, first update the `mcp.json` file as described in the next step on this page, then follow the [Copilot documentation (starting from step 2)](https://docs.github.com/en/copilot/customizing-copilot/extending-copilot-chat-with-mcp#configuring-mcp-servers-in-visual-studio-code) to configure MCP servers in VS Code Chat.
***
### Step 3: Configure the MCP File
There are two transport modes for MCP servers: `stdio` and `sse`.
* **Stdio**: Best for local development. The server runs locally, and the client connects directly to it.
* **SSE**: Designed for server deployments. However, since clients don't yet support SSE connections with all the features we need, you need a proxy server. The proxy acts as a `stdio` server for the client and communicates with the SSE server in the background.
#### Option 1: Stdio Server
Add the following configuration to your MCP file:
For example, if the prefix is `@strapi`, the key will be `@strapi:
For example, `["GET", "POST"]`
Some examples:
* `path: "/api/restaurants/:id"`
* `path: "/api/restaurants"`
Available sources are:
* `ip`: The IP address of the user.
* `header`: The value of a header key. You should pass the source in the `header.
For example, `header.Authorization` will use the value of the `Authorization`
* `fixed-window`: The fixed-window algorithm divides time into fixed intervals. Each interval has a set limit of allowed requests. When a new interval starts, the count resets.
* `sliding-window`: The sliding-window algorithm uses a rolling time frame. It considers requests from the past X time units, continuously moving forward. This provides a smoother distribution of requests over time.
* `token-bucket`: The token-bucket algorithm uses a bucket that fills with tokens at a steady rate. Each request consumes a token. If the bucket is empty, requests are denied. This allows for bursts of traffic while maintaining a long-term rate limit.
For example, `20s` means 20 seconds.
**What if your product becomes popular and starts to gain high and steady
traffic?**
Most of the serverless products start to lose their spell if the service
receives steady and high traffic as it starts to cost higher than
server/instance based pricing models. To overcome this situation we give you
option to purchase Pro Plan. In Pro plan you can set fixed
price per month with a restriction on max throughput and data size. For high and
steady throughput use cases, enterprise databases cost less than serverless one.
The good thing is you can start your database with pay-as-you-go pricing and
move it enterprise when you want. See [enterprise plans](/redis/overall/enterprise) for more
information.
Even if you choose not to upgrade to the Pro plan, Upstash guarantees
transparent billing without any unexpected surprises. Each Upstash database has
a predefined monthly maximum price, known as the "Ceiling Price." For
pay-as-you-go (PAYG) databases, this ceiling price is set at \$360 per month.
Therefore, even if your application experiences a significant surge in traffic,
such as reaching the front page of HackerNews, your Upstash database will not
exceed a maximum cost of \$360 per month.
# Prod Pack & Enterprise
Source: https://upstash.com/docs/redis/overall/enterprise
Upstash has Prod Pack and Enterprise plans for customers with critical production workloads. Prod Pack and Enterprise plans include additional monitoring and security features in addition to higher capacity limits and more powerful resources
Prod Pack -> Per database
Enterprise contract -> Per account
Prod Pack are an add-on per database available to both pay-as-you-go and fixed-price plans, not per account. You can have databases on different plans in the same account and each is charged separately. Meanwhile, Enterprise plans are per account, not per database. All of your databases can be included in the same Enterprise plan covering all of your databases.
# Prod Pack Features
These features are available on Prod Pack databases.
### Uptime SLA
All Prod Pack databases come with an SLA guaranteeing 99.99% uptime. For mission-critical data where uptime is crucial, we recommend Prod Pack plans.
### RBAC
Role-Based Access Control (RBAC) is a security model that manages database access. You can create multiple users with different roles to control their actions on your databases.
We recommend using RBAC if your database is accessible to multiple developers.
### SOC-2 Type 2 Report
We have a SOC 2 Type 2 report available for our Prod Pack and Enterprise plans. You can request access to the report by contacting [support@upstash.com](mailto:support@upstash.com).
### Prometheus Metrics
Prometheus is an open-source monitoring system widely used for monitoring and alerting in cloud-native and containerized environments.
Upstash Prod Pack and Enterprise plans offer Prometheus metrics collection, enabling you to monitor your Redis databases with Prometheus in addition to console metrics.
### Datadog Integration
Upstash Prod Pack and Enterprise plans include integration with Datadog, allowing you to monitor your Redis databases with Datadog in addition to console metrics.
### More metrics on the Console
Max interval of the metrics that are available on the Upstash Console increases from one week to one month for databases with Prod Pack.
### High Availability for Read Regions
With Prod Pack add-on, read regions of your database are [highly available](https://upstash.com/docs/redis/features/replication#high-availability). This ensures that if one read replica fails, you can read from another read replica in the same region without any additional latency.
### More Backup Capability
Backups up to 3 days are possible with the Prod Pack add-on.
### Encryption at REST
Encrypts the block storage where your data is persisted and stored.
# Enterprise Features
All Prod Pack features can be included in the Enterprise plan upon request. Additionally, Enterprise plans include:
### Professional Support
All of the databases in the Enterprise plan get access to our professional support. The plan includes response time SLAs and priority access to our support team. Check out the [support page](https://upstash.com/docs/common/help/prosupport) for more details.
The below features are available upon request for Enterprise customers.
### SSO
Single Sign-On (SSO) allows you to use your existing identity provider to authenticate users for your Upstash account. This feature is available upon request for Enterprise customers.
### VPC Peering and Private Links
VPC Peering and Private Links enable you to connect your databases to your VPCs and other private networks, enhancing isolation and security while reducing data transfer costs. This feature is available upon request for Enterprise customers.
### Configurable Backups
Hourly backups with customizable retention are available upon request for Enterprise customers.
### Access Logs
Enterprise customers can request access logs to the databases.
### More Resources
A non-Enterprise Upstash account can create up to 100 databases and 10 teams. Enterprise customers can request more resources.
### HIPAA Compliance
HIPAA reports are available with our Enterprise plans, along with the SOC 2 Type 2 report. To request access, please contact [support@upstash.com](mailto:support@upstash.com).
## How to Upgrade
You can activate Prod Pack on the database details page in the console. For the Enterprise plan, contact [support@upstash.com](mailto:support@upstash.com).
# Getting Started
Source: https://upstash.com/docs/redis/overall/getstarted
Create an Upstash Redis database in seconds
Upstash Redis is a **highly available, infinitely scalable** Redis-compatible database:
* 99.99% uptime guarantee with auto-scaling
* Ultra-low latency worldwide
* Multi-region replication
* Durable, persistent storage without sacrificing performance
* Automatic backups
* Optional SOC-2 compliance, encryption at rest and much more
***
## 1. Create an Upstash Redis Database
Once you're logged in, create a database by clicking `+ Create Database` in the upper right corner. A dialog opens up:
**Database Name:** Enter a name for your database.
**Primary Region and Read Regions:** For optimal performance, select the Primary Region closest to where most of your writes will occur. Select the read region(s) where most of your reads will occur.
Once you click `Next` and select a plan, your database is running and ready to connect:
***
## 2. Connect to Your Database
You can connect to Upstash Redis with any Redis client. For simplicity, we'll use `redis-cli`. See the [Connect Your Client](../howto/connectclient) section for connecting via our TypeScript or Python SDKs and other clients.
The Redis CLI is included in the official Redis distribution. If you don't
have Redis installed, you can get it [here](https://redis.io/docs/latest/operate/oss_and_stack/install/install-redis/).
Connect to your database and execute commands on it:
```bash
> redis-cli --tls -a PASSWORD -h ENDPOINT -p PORT
ENDPOINT:PORT> set counter 0
OK
ENDPOINT:PORT> get counter
"0"
ENDPOINT:PORT> incr counter
(int) 1
ENDPOINT:PORT> incr counter
(int) 2
```
As you run commands, you'll see updates to your database metrics in (almost) real-time. These database metrics are refreshed every 10 seconds.
Congratulations! You have created an ultra-fast Upstash Redis database! š
Clicking on the application will direct you to the application details page, where you can perform the integration process. Switch to the **Settings** tab in the application details, and proceed to **Integrations** section. You will see various Worker integrations listed. To proceed, click the **Add Integration** button associated with the Upstash Redis.
On the Integration page, connect to your Upstash account. Then, select the related database from the dropdown menu. Finalize the process by pressing Save button.
#### Setting up Manually
Navigate to [Upstash Console](https://console.upstash.com) and copy/paste your `UPSTASH_REDIS_REST_URL` and `UPSTASH_REDIS_REST_TOKEN` to your `wrangler.toml` as below.
```yaml
[vars]
UPSTASH_REDIS_REST_URL="REPLACE_HERE"
UPSTASH_REDIS_REST_TOKEN="REPLACE_HERE"
```
### Test and Deploy
You can test the function locally with `npx wrangler dev`
Deploy your function to Cloudflare with `npx wrangler deploy`
The endpoint of the function will be provided to you, once the deployment is done.
### Repo
Javascript:
[https://github.com/upstash/upstash-redis/tree/main/examples/cloudflare-workers](https://github.com/upstash/upstash-redis/tree/main/examples/cloudflare-workers)
Typescript:
[https://github.com/upstash/upstash-redis/tree/main/examples/cloudflare-workers-with-typescript](https://github.com/upstash/upstash-redis/tree/main/examples/cloudflare-workers-with-typescript)
Wrangler 1:
[https://github.com/upstash/upstash-redis/tree/main/examples/cloudflare-workers-with-wrangler-1](https://github.com/upstash/upstash-redis/tree/main/examples/cloudflare-workers-with-wrangler-1)
# Deno Deploy
Source: https://upstash.com/docs/redis/quickstarts/deno-deploy
This is a step-by-step guide on how to use Upstash Redis to create a view
counter in your Deno deploy project.
### Create a database
Create a Redis database using [Upstash Console](https://console.upstash.com) or
[Upstash CLI](https://github.com/upstash/cli). Select the global to minimize the
latency from all edge locations. Copy the `UPSTASH_REDIS_REST_URL` and
`UPSTASH_REDIS_REST_TOKEN` for the next steps.
### Create a Deno deploy project
Go to [https://dash.deno.com/projects](https://dash.deno.com/projects) and
create a new playground project.
### 2. Edit the handler function
Then paste the following code into the browser editor:
```ts
import { serve } from "https://deno.land/std@0.142.0/http/server.ts";
import { Redis } from "https://deno.land/x/upstash_redis@v1.14.0/mod.ts";
serve(async (_req: Request) => {
if (!_req.url.endsWith("favicon.ico")) {
const redis = new Redis({
url: "UPSTASH_REDIS_REST_URL",
token: "UPSTASH_REDIS_REST_TOKEN",
});
const counter = await redis.incr("deno-counter");
return new Response(JSON.stringify({ counter }), { status: 200 });
}
});
```
### 3. Deploy and Run
Simply click on `Save & Deploy` at the top of the screen.
# DigitalOcean
Source: https://upstash.com/docs/redis/quickstarts/digitalocean
After selecting Name, Plan and Region, click `Add Upstash Redis` button.
### Connecting to Database - SSO
After creating database, Overview/Details page will be opened.
Environment variables can be shown in that page.
While creating a Droplet, Upstash Addon can be selected and environment
variables are automatically injected to Droplet.
These Steps can be followed: `Create --> Droplets --> Marketplace Add-Ons` then
select the previously created Upstash Redis Addon.
Upstash also support Single Sign-On from DigitalOcean to Upstash Console.
So databases created from DigitalOcean can benefit from Upstash Console
features.
In order to access Upstash Console from DigitalOcean just click `Dashboard` link
when you create the Upstash addon.
# Django
Source: https://upstash.com/docs/redis/quickstarts/django
### Introduction
In this quickstart tutorial, we will demonstrate how to use Django with Upstash Redis to build a simple web application that increments a counter every time the homepage is accessed.
### Environment Setup
First, install Django and the Upstash Redis client for Python:
```shell
pip install django
pip install upstash-redis
```
### Database Setup
Create a Redis database using the [Upstash Console](https://console.upstash.com) or [Upstash CLI](https://github.com/upstash/cli) and export the `UPSTASH_REDIS_REST_URL` and `UPSTASH_REDIS_REST_TOKEN` to your environment:
```shell
export UPSTASH_REDIS_REST_URL=Redix Demo
<%= if @text do %> <%= @text %> <% end %> <%= if @weather do %>
<%= if @location do %>
Location:
<%= @location %>
<% end %>
<% end %>
Weather: <%= @weather %> Ā°C
Counter: {count}
Counter: {count}
Counter: {count}
Counter: { count }
'''
return HttpResponse(html)
```
### Run & Deploy
Run the app locally with `python manage.py runserver`, check `http://localhost:8000/`
Deploy your app with `vercel`
Set `UPSTASH_REDIS_REST_URL` and `UPSTASH_REDIS_REST_TOKEN` in your project's Settings -> Environment Variables. Redeploy from Deployments tab.
You can also integrate your Vercel projects with Upstash using Vercel
Integration module. Check [this article](../howto/vercelintegration).
# ECHO
Source: https://upstash.com/docs/redis/sdks/py/commands/auth/echo
Returns a message back to you. Useful for debugging the connection.
## Arguments
A message to send to the server.
## Response
The same message you sent.
```py Example
assert redis.echo("hello world") == "hello world"
```
# PING
Source: https://upstash.com/docs/redis/sdks/py/commands/auth/ping
Send a ping to the server and get a response if the server is alive.
## Arguments
No arguments
## Response
`PONG`
```py Example
assert redis.ping() == "PONG"
```
# BITCOUNT
Source: https://upstash.com/docs/redis/sdks/py/commands/bitmap/bitcount
Count the number of set bits.
The `BITCOUNT` command in Redis is used to count the number of set bits (bits with a value of 1) in a range of bytes within a key that is stored as a binary string. It is primarily used for bit-level operations on binary data stored in Redis.
## Arguments
The key to get.
Specify the range of bytes within the binary string to count the set bits. If not provided, it counts set bits in the entire string.
Either specify both `start` and `end` or neither.
Specify the range of bytes within the binary string to count the set bits. If not provided, it counts set bits in the entire string.
Either specify both `start` and `end` or neither.
## Response
The number of set bits in the specified range.
```py Example
redis.setbit("mykey", 7, 1)
redis.setbit("mykey", 8, 1)
redis.setbit("mykey", 9, 1)
# With range
assert redis.bitcount("mykey", 0, 10) == 3
# Without range
assert redis.bitcount("mykey") == 3
```
# BITFIELD
Source: https://upstash.com/docs/redis/sdks/py/commands/bitmap/bitfield
Sets or gets parts of a bitfield
The `bitfield` function returns a `BitFieldCommands` instance that can be used
to execute multiple bitfield operations in a single command.
The encoding can be a signed or unsigned integer, by prefixing the type with
`i` or `u`. For example, `i4` is a signed 4-bit integer, and `u8` is an
unsigned 8-bit integer.
```py
redis.set("mykey", "")
# Sets the first 4 bits to 1
# Increments the next 4 bits by 1
result = redis.bitfield("mykey")
.set("u4", 0, 16)
.incr("u4", 4, 1)
.execute()
assert result == [0, 1]
```
## Commands
### `get(type: str, offset: int)`
Returns a value from the bitfield at the given offset.
### `set(type: str, offset: int, value: int)`
Sets a value and returns the old value.
### `incr(type: str, offset: int, increment: int)`
Increments a value and returns the new value.
## Arguments
The string key to operate on.
## Response
A list of integers, one for each operation.
```py Get
redis.set("mykey", "\x05\x06\x07")
result = redis.bitfield("mykey") \
.get("u8", 0) \
.get("u8", 8) \
.get("u8", 16) \
.execute()
assert result == [5, 6, 7]
```
```py Set
redis.set("mykey", "")
result = redis.bitfield("mykey") \
.set("u4", 0, 16) \
.set("u4", 4, 1) \
.execute()
assert result == [0, 1]
```
```py Incr
redis.set("mykey", "")
# Increment offset 0 by 16, return
# Increment offset 4 by 1
result = redis.bitfield("mykey") \
.incr("u4", 0, 16) \
.incr("u4", 4, 1) \
.execute()
assert result == [0, 1]
```
# BITOP
Source: https://upstash.com/docs/redis/sdks/py/commands/bitmap/bitop
Perform bitwise operations between strings.
The `BITOP` command in Redis is used to perform bitwise operations on multiple keys (or Redis strings) and store the result in a destination key. It is primarily used for performing logical AND, OR, XOR, and NOT operations on binary data stored in Redis.
## Arguments
Specifies the type of bitwise operation to perform, which can be one of the
following: `AND`, `OR`, `XOR`, or `NOT`.
The key to store the result of the operation in.
One or more keys to perform the operation on.
## Response
The size of the string stored in the destination key.
```py Example
# key1 = 00000001
# key2 = 00000010
redis.setbit("key1", 0, 1)
redis.setbit("key2", 0, 0)
redis.setbit("key2", 1, 1)
assert redis.bitop("AND", "dest", "key1", "key2") == 1
# result = 00000000
assert redis.getbit("dest", 0) == 0
assert redis.getbit("dest", 1) == 0
```
# BITPOS
Source: https://upstash.com/docs/redis/sdks/py/commands/bitmap/bitpos
Find the position of the first set or clear bit (bit with a value of 1 or 0) in a Redis string key.
## Arguments
The key to search in.
The key to store the result of the operation in.
The index to start searching at.
The index to stop searching at.
## Response
The index of the first occurrence of the bit in the string.
```py Example
redis.setbit("mykey", 7, 1)
redis.setbit("mykey", 8, 1)
assert redis.bitpos("mykey", 1) == 7
assert redis.bitpos("mykey", 0) == 0
# With a range
assert redis.bitpos("mykey", 1, 0, 2) == 0
assert redis.bitpos("mykey", 1, 2, 3) == -1
```
```py With Range
redis.bitpos("key", 1, 5, 20)
```
# GETBIT
Source: https://upstash.com/docs/redis/sdks/py/commands/bitmap/getbit
Retrieve a single bit.
## Arguments
The key of the bitset
Specify the offset at which to get the bit.
## Response
The bit value stored at offset.
```py Example
bit = redis.getbit(key, 4)
```
# SETBIT
Source: https://upstash.com/docs/redis/sdks/py/commands/bitmap/setbit
Set a single bit in a string.
## Arguments
The key of the bitset
Specify the offset at which to set the bit.
The bit to set
## Response
The original bit value stored at offset.
```py Example
original_bit = redis.setbit(key, 4, 1)
```
# DEL
Source: https://upstash.com/docs/redis/sdks/py/commands/generic/del
Removes the specified keys. A key is ignored if it does not exist.
## Arguments
One or more keys to remove.
## Response
The number of keys that were removed.
```py Example
redis.set("key1", "Hello")
redis.set("key2", "World")
redis.delete("key1", "key2")
assert redis.get("key1") is None
assert redis.get("key2") is None
```
# EXISTS
Source: https://upstash.com/docs/redis/sdks/py/commands/generic/exists
Check if a key exists.
## Arguments
One or more keys to check.
## Response
The number of keys that exist
```py Example
redis.set("key1", "Hello")
redis.set("key2", "World")
assert redis.exists("key1", "key2") == 2
redis.delete("key1")
assert redis.exists("key1", "key2") == 1
```
# EXPIRE
Source: https://upstash.com/docs/redis/sdks/py/commands/generic/expire
Sets a timeout on key. The key will automatically be deleted.
## Arguments
The key to set the timeout on.
The timeout in seconds as int or datetime.timedelta object
Set expiry only when the key has no expiry
Set expiry only when the key has an existing expiry
Set expiry only when the new expiry is greater than current one
Set expiry only when the new expiry is less than current one
## Response
`True` if the timeout was set
```py Example
# With seconds
redis.set("mykey", "Hello")
redis.expire("mykey", 5)
assert redis.get("mykey") == "Hello"
time.sleep(5)
assert redis.get("mykey") is None
# With a timedelta
redis.set("mykey", "Hello")
redis.expire("mykey", datetime.timedelta(seconds=5))
```
# EXPIREAT
Source: https://upstash.com/docs/redis/sdks/py/commands/generic/expireat
Sets a timeout on key. The key will automatically be deleted.
## Arguments
The key to set the timeout on.
The timeout in unix seconds timestamp as int or a datetime.datetime object.
Set expiry only when the key has no expiry
Set expiry only when the key has an existing expiry
Set expiry only when the new expiry is greater than current one
Set expiry only when the new expiry is less than current one
## Response
`True` if the timeout was set
```py Example
# With a datetime object
redis.set("mykey", "Hello")
redis.expireat("mykey", datetime.datetime.now() + datetime.timedelta(seconds=5))
# With a unix timestamp
redis.set("mykey", "Hello")
redis.expireat("mykey", int(time.time()) + 5)
```
# KEYS
Source: https://upstash.com/docs/redis/sdks/py/commands/generic/keys
Returns all keys matching pattern.
This command may block the DB for a long time, depending on its size. We advice against using it in production. Use [SCAN](/redis/sdks/py/commands/generic/scan) instead.
## Arguments
A glob-style pattern. Use `*` to match all keys.
## Response
Array of keys matching the pattern.
```py Example
keys = redis.keys("prefix*")
```
```py Match All
keys = redis.keys("*")
```
# PERSIST
Source: https://upstash.com/docs/redis/sdks/py/commands/generic/persist
Remove any timeout set on the key.
## Arguments
The key to persist
## Response
`True` if the timeout was set
```py Example
redis.set("key1", "Hello")
redis.expire("key1", 10)
assert redis.ttl("key1") == 10
redis.persist("key1")
assert redis.ttl("key1") == -1
```
# PEXPIRE
Source: https://upstash.com/docs/redis/sdks/py/commands/generic/pexpire
Sets a timeout on key. After the timeout has expired, the key will automatically be deleted.
## Arguments
The key to expire.
The timeout in milliseconds as int or datetime.timedelta
Set expiry only when the key has no expiry
Set expiry only when the key has an existing expiry
Set expiry only when the new expiry is greater than current one
Set expiry only when the new expiry is less than current one
## Response
`True` if the timeout was set
```py Example
# With milliseconds
redis.set("mykey", "Hello")
redis.expire("mykey", 500)
# With a timedelta
redis.set("mykey", "Hello")
redis.expire("mykey", datetime.timedelta(milliseconds=500))
```
# PEXPIREAT
Source: https://upstash.com/docs/redis/sdks/py/commands/generic/pexpireat
Sets a timeout on key. After the timeout has expired, the key will automatically be deleted.
## Arguments
The key to expire.
The timeout in unix milliseconds timestamp as int or a datetime.datetime object.
Set expiry only when the key has no expiry
Set expiry only when the key has an existing expiry
Set expiry only when the new expiry is greater than current one
Set expiry only when the new expiry is less than current one
## Response
`True` if the timeout was set
```py Example
# With a unix timestamp
redis.set("mykey", "Hello")
redis.pexpireat("mykey", int(time.time() * 1000) )
# With a datetime object
redis.set("mykey", "Hello")
redis.pexpireat("mykey", datetime.datetime.now() + datetime.timedelta(seconds=5))
```
# PTTL
Source: https://upstash.com/docs/redis/sdks/py/commands/generic/pttl
Return the expiration in milliseconds of a key.
## Arguments
The key
## Response
The number of milliseconds until this expires, negative if the key does not exist or does not have an expiration set.
```py Example
redis.set("key1", "Hello")
assert redis.pttl("key1") == -1
redis.expire("key1", 1000)
assert redis.pttl("key1") > 0
redis.persist("key1")
assert redis.pttl("key1") == -1
```
# RANDOMKEY
Source: https://upstash.com/docs/redis/sdks/py/commands/generic/randomkey
Returns a random key from database
## Arguments
No arguments
## Response
A random key from database, or `None` when database is empty.
```py Example
assert redis.randomkey() is None
redis.set("key1", "Hello")
redis.set("key2", "World")
assert redis.randomkey() is not None
```
# RENAME
Source: https://upstash.com/docs/redis/sdks/py/commands/generic/rename
Rename a key
Renames a key and overwrites the new key if it already exists.
Throws an exception if the key does not exist.
## Arguments
The original key.
A new name for the key.
## Response
`True` if key was renamed
```py Example
redis.set("key1", "Hello")
redis.rename("key1", "key2")
assert redis.get("key1") is None
assert redis.get("key2") == "Hello"
# Renaming a nonexistent key throws an exception
redis.rename("nonexistent", "key3")
```
# RENAMENX
Source: https://upstash.com/docs/redis/sdks/py/commands/generic/renamenx
Rename a key if it does not already exist.
Renames a key, only if the new key does not exist.
Throws an exception if the key does not exist.
## Arguments
The original key.
A new name for the key.
## Response
`True` if key was renamed
```py Example
redis.set("key1", "Hello")
redis.set("key2", "World")
# Rename failed because "key2" already exists.
assert redis.renamenx("key1", "key2") == False
assert redis.renamenx("key1", "key3") == True
assert redis.get("key1") is None
assert redis.get("key2") == "World"
assert redis.get("key3") == "Hello"
```
# SCAN
Source: https://upstash.com/docs/redis/sdks/py/commands/generic/scan
Scan the database for keys.
## Arguments
The cursor, use `0` in the beginning and then use the returned cursor for subsequent calls.
Glob-style pattern to filter by field names.
Number of fields to return per call.
Filter by type.
For example `string`, `hash`, `set`, `zset`, `list`, `stream`.
## Response
The new cursor and the keys as a tuple.
If the new cursor is `0` the iteration is complete.
Use the new cursor for subsequent calls.
```py Example
# Get all keys
cursor = 0
results = []
while True:
cursor, keys = redis.scan(cursor, match="*")
results.extend(keys)
if cursor == 0:
break
```
# TOUCH
Source: https://upstash.com/docs/redis/sdks/py/commands/generic/touch
Alters the last access time of one or more keys
## Arguments
One or more keys.
## Response
The number of keys that were touched.
```py Example
redis.touch("key1", "key2", "key3")
```
# TTL
Source: https://upstash.com/docs/redis/sdks/py/commands/generic/ttl
Return the expiration in seconds of a key.
## Arguments
The key
## Response
The number of seconds until this expires, negative if the key does not exist or does not have an expiration set.
```py Example
# Get the TTL of a key
redis.set("my-key", "value")
assert redis.ttl("my-key") == -1
redis.expire("my-key", 10)
assert redis.ttl("my-key") > 0
# Non existent key
assert redis.ttl("non-existent-key") == -2
```
# TYPE
Source: https://upstash.com/docs/redis/sdks/py/commands/generic/type
Get the type of a key.
## Arguments
The key to get.
## Response
The type of the key.
One of `string` | `list` | `set` | `zset` | `hash` | `none`
```py Example
redis.set("key1", "Hello")
assert redis.type("key1") == "string"
redis.lpush("key2", "Hello")
assert redis.type("key2") == "list"
assert redis.type("non-existent-key") == "none"
```
# UNLINK
Source: https://upstash.com/docs/redis/sdks/py/commands/generic/unlink
Removes the specified keys. A key is ignored if it does not exist.
## Arguments
One or more keys to unlink.
## Response
The number of keys that were unlinked.
```py Basic
assert redis.unlink("key1", "key2", "key3") == 3
```
# HDEL
Source: https://upstash.com/docs/redis/sdks/py/commands/hash/hdel
Deletes one or more hash fields.
## Arguments
The key to get.
One or more fields to delete.
## Response
The number of fields that were removed from the hash.
```py Example
redis.hset("myhash", "field1", "Hello")
redis.hset("myhash", "field2", "World")
assert redis.hdel("myhash", "field1", "field2") == 2
```
# HEXISTS
Source: https://upstash.com/docs/redis/sdks/py/commands/hash/hexists
Checks if a field exists in a hash.
## Arguments
The key to get.
The field to check.
## Response
`True` if the hash contains `field`. `False` if the hash does not contain `field`, or `key` does not exist.
```py Example
redis.hset("key", "field", "value")
assert redis.hexists("key", "field") == True
```
# HEXPIRE
Source: https://upstash.com/docs/redis/sdks/py/commands/hash/hexpire
Set a timeout on a hash field in seconds.
## Arguments
The key of the hash.
The field or list of fields within the hash to set the expiry for.
The timeout in seconds as an integer or a `datetime.timedelta` object.
Set expiry only when the field has no expiry. Defaults to `False`.
Set expiry only when the field has an existing expiry. Defaults to `False`.
Set expiry only when the new expiry is greater than the current one. Defaults to `False`.
Set expiry only when the new expiry is less than the current one. Defaults to `False`.
## Response
A list of integers indicating whether the expiry was successfully set.
* `-2` if the field does not exist in the hash or if key doesn't exist.
* `0` if the expiration was not set due to the condition.
* `1` if the expiration was successfully set.
* `2` if called with 0 seconds/milliseconds or a past Unix time.
For more details, see [HEXPIRE documentation](https://redis.io/commands/hexpire).
```py Example
redis.hset(hash_name, field, value)
assert redis.hexpire(hash_name, field, 1) == [1]
```
# HEXPIREAT
Source: https://upstash.com/docs/redis/sdks/py/commands/hash/hexpireat
Sets an expiration time for field(s) in a hash in seconds since the Unix epoch.
## Arguments
The key of the hash.
The field or list of fields to set an expiration time for.
The expiration time as a Unix timestamp in seconds.
Set expiry only when the field has no expiry. Defaults to `False`.
Set expiry only when the field has an existing expiry. Defaults to `False`.
Set expiry only when the new expiry is greater than the current one. Defaults to `False`.
Set expiry only when the new expiry is less than the current one. Defaults to `False`.
## Response
A list of integers indicating whether the expiry was successfully set.
* `-2` if the field does not exist in the hash or if the key doesn't exist.
* `0` if the expiration was not set due to the condition.
* `1` if the expiration was successfully set.
* `2` if called with 0 seconds/milliseconds or a past Unix time.
For more details, see [HEXPIREAT documentation](https://redis.io/commands/hexpireat).
```py Example
redis.hset(hash_name, field, value)
assert redis.hexpireat(hash_name, field, int(time.time()) + 10) == [1]
```
# HEXPIRETIME
Source: https://upstash.com/docs/redis/sdks/py/commands/hash/hexpiretime
Retrieves the expiration time of field(s) in a hash in seconds.
## Arguments
The key of the hash.
The field or list of fields to retrieve the expiration time for.
## Response
A list of integers representing the expiration time in seconds since the Unix epoch.
* `-2` if the field does not exist in the hash or if the key doesn't exist.
* `-1` if the field exists but has no associated expiration.
For more details, see [HEXPIRETIME documentation](https://redis.io/commands/hexpiretime).
```py Example
redis.hset(hash_name, field, value)
redis.hexpireat(hash_name, field, int(time.time()) + 10)
assert redis.hexpiretime(hash_name, field) == [1697059200]
```
# HGET
Source: https://upstash.com/docs/redis/sdks/py/commands/hash/hget
Retrieves the value of a hash field.
## Arguments
The key to get.
The field to get.
## Response
The value of the field, or `null`, when field is not present in the hash or key does not exist.
```py Example
redis.hset("myhash", "field1", "Hello")
assert redis.hget("myhash", "field1") == "Hello"
assert redis.hget("myhash", "field2") is None
```
# HGETALL
Source: https://upstash.com/docs/redis/sdks/py/commands/hash/hgetall
Retrieves all fields from a hash.
## Arguments
The key to get.
## Response
An object with all fields in the hash.
```py Example
redis.hset("myhash", values={
"field1": "Hello",
"field2": "World"
})
assert redis.hgetall("myhash") == {"field1": "Hello", "field2": "World"}
```
# HINCRBY
Source: https://upstash.com/docs/redis/sdks/py/commands/hash/hincrby
Increments the value of a hash field by a given amount
If the hash field does not exist, it is set to 0 before performing the operation.
## Arguments
The key of the hash.
The field to increment
How much to increment the field by. Can be negative to subtract.
## Response
The new value of the field after the increment.
```py Example
redis.hset("myhash", "field1", 5)
assert redis.hincrby("myhash", "field1", 10) == 15
```
# HINCRBYFLOAT
Source: https://upstash.com/docs/redis/sdks/py/commands/hash/hincrbyfloat
Increments the value of a hash field by a given float value.
## Arguments
The key of the hash.
The field to increment
How much to increment the field by. Can be negative to subtract.
## Response
The new value of the field after the increment.
```py Example
redis.hset("myhash", "field1", 5.5)
assert redis.hincrbyfloat("myhash", "field1", 10.1) - 15.6 < 0.0001
```
# HKEYS
Source: https://upstash.com/docs/redis/sdks/py/commands/hash/hkeys
Return all field names in the hash stored at key.
## Arguments
The key of the hash.
## Response
The field names of the hash
```py Example
redis.hset("myhash", values={
"field1": "Hello",
"field2": "World"
})
assert redis.hkeys("myhash") == ["field1", "field2"]
```
# HLEN
Source: https://upstash.com/docs/redis/sdks/py/commands/hash/hlen
Returns the number of fields contained in the hash stored at key.
## Arguments
The key of the hash.
## Response
How many fields are in the hash.
```py Example
assert redis.hlen("myhash") == 0
redis.hset("myhash", values={
"field1": "Hello",
"field2": "World"
})
assert redis.hlen("myhash") == 2
```
# HMGET
Source: https://upstash.com/docs/redis/sdks/py/commands/hash/hmget
Return the requested fields and their values.
## Arguments
The key of the hash.
One or more fields to get.
## Response
An object containing the fields and their values.
```py Example
redis.hset("myhash", values={
"field1": "Hello",
"field2": "World"
})
assert redis.hmget("myhash", "field1", "field2") == ["Hello", "World"]
```
# HMSET
Source: https://upstash.com/docs/redis/sdks/py/commands/hash/hmset
Write multiple fields to a hash.
## Arguments
The key of the hash.
A dictionary of fields and their values.
## Response
The number of fields that were added.
```py Example
# Set multiple fields
assert redis.hset("myhash"{
"field1": "Hello",
"field2": "World"
}) == 2
```
# HPERSIST
Source: https://upstash.com/docs/redis/sdks/py/commands/hash/hpersist
Remove the expiration from one or more hash fields.
## Arguments
The key of the hash.
The field or list of fields within the hash to remove the expiry from.
## Response
A list of integers indicating the result for each field:
* `-2` if the field does not exist in the hash or if the key doesn't exist.
* `-1` if the field exists but has no associated expiration set.
* `1` if the expiration was successfully removed.
For more details, see [HPERSIST documentation](https://redis.io/commands/hpersist).
```py Example
redis.hset(hash_name, field, value)
redis.hpexpire(hash_name, field, 1000)
assert redis.hpersist(hash_name, field) == [1]
```
# HPEXPIRE
Source: https://upstash.com/docs/redis/sdks/py/commands/hash/hpexpire
Set a timeout on a hash field in milliseconds.
## Arguments
The key of the hash.
The field or list of fields within the hash to set the expiry for.
The timeout in milliseconds as an integer or a `datetime.timedelta` object.
Set expiry only when the field has no expiry. Defaults to `False`.
Set expiry only when the field has an existing expiry. Defaults to `False`.
Set expiry only when the new expiry is greater than the current one. Defaults to `False`.
Set expiry only when the new expiry is less than the current one. Defaults to `False`.
## Response
A list of integers indicating whether the expiry was successfully set.
* `-2` if the field does not exist in the hash or if key doesn't exist.
* `0` if the expiration was not set due to the condition.
* `1` if the expiration was successfully set.
* `2` if called with 0 seconds/milliseconds or a past Unix time.
For more details, see [HPEXPIRE documentation](https://redis.io/commands/hpexpire).
```py Example
redis.hset(hash_name, field, value)
assert redis.hpexpire(hash_name, field, 1000) == [1]
```
# HPEXPIREAT
Source: https://upstash.com/docs/redis/sdks/py/commands/hash/hpexpireat
Sets an expiration time for field(s) in a hash in milliseconds since the Unix epoch.
## Arguments
The key of the hash.
The field or list of fields to set an expiration time for.
The expiration time as a Unix timestamp in milliseconds.
Set expiry only when the field has no expiry. Defaults to `False`.
Set expiry only when the field has an existing expiry. Defaults to `False`.
Set expiry only when the new expiry is greater than the current one. Defaults to `False`.
Set expiry only when the new expiry is less than the current one. Defaults to `False`.
## Response
A list of integers indicating whether the expiry was successfully set.
* `-2` if the field does not exist in the hash or if the key doesn't exist.
* `0` if the expiration was not set due to the condition.
* `1` if the expiration was successfully set.
* `2` if called with 0 seconds/milliseconds or a past Unix time.
For more details, see [HPEXPIREAT documentation](https://redis.io/commands/hpexpireat).
```py Example
redis.hset(hash_name, field, value)
assert redis.hpexpireat(hash_name, field, int(time.time() * 1000) + 1000) == [1]
```
# HPEXPIRETIME
Source: https://upstash.com/docs/redis/sdks/py/commands/hash/hpexpiretime
Retrieves the expiration time of a field in a hash in milliseconds.
## Arguments
The key of the hash.
The field or list of fields to retrieve the expiration time for.
## Response
A list of integers representing the expiration time in milliseconds since the Unix epoch.
* `-2` if the field does not exist in the hash or if the key doesn't exist.
* `-1` if the field exists but has no associated expiration.
For more details, see [HPEXPIRETIME documentation](https://redis.io/commands/hpexpiretime).
```py Example
redis.hset(hash_name, field, value)
redis.hpexpireat(hash_name, field, int(time.time() * 1000) + 1000)
assert redis.hpexpiretime(hash_name, field) == [1697059200000]
```
# HPTTL
Source: https://upstash.com/docs/redis/sdks/py/commands/hash/hpttl
Retrieves the remaining time-to-live (TTL) for field(s) in a hash in milliseconds.
## Arguments
The key of the hash.
The field or list of fields to retrieve the TTL for.
## Response
A list of integers representing the remaining TTL in milliseconds for each field.
* `-2` if the field does not exist in the hash or if the key doesn't exist.
* `-1` if the field exists but has no associated expiration.
For more details, see [HPTTL documentation](https://redis.io/commands/hpttl).
```py Example
redis.hset(hash_name, field, value)
redis.hpexpire(hash_name, field, 1000)
assert redis.hpttl(hash_name, field) == [950]
```
# HRANDFIELD
Source: https://upstash.com/docs/redis/sdks/py/commands/hash/hrandfield
Return a random field from a hash
## Arguments
The key of the hash.
Optionally return more than one field.
Return the values of the fields as well.
## Response
An object containing the fields and their values.
```py Single
redis.hset("myhash", values={
"field1": "Hello",
"field2": "World"
})
assert redis.hrandfield("myhash") in ["field1", "field2"]
```
```py Multiple
redis.hset("myhash", values={
"field1": "Hello",
"field2": "World"
})
assert redis.hrandfield("myhash", count=2) in [
["field1", "field2"],
["field2", "field1"]
]
```
```py With Values
redis.hset("myhash", values={
"field1": "Hello",
"field2": "World"
})
assert redis.hrandfield("myhash", count=1, withvalues=True) in [
{"field1": "Hello"},
{"field2": "World"}
]
```
# HSCAN
Source: https://upstash.com/docs/redis/sdks/py/commands/hash/hscan
Scan a hash for fields.
## Arguments
The key of the hash.
The cursor, use `0` in the beginning and then use the returned cursor for subsequent calls.
Glob-style pattern to filter by field names.
Number of fields to return per call.
## Response
The new cursor and the fields.
If the new cursor is `0` the iteration is complete.
```py Basic
# Get all members of a hash.
cursor = 0
results = []
while True:
cursor, keys = redis.hscan("myhash", cursor, match="*")
results.extend(keys)
if cursor == 0:
break
```
# HSET
Source: https://upstash.com/docs/redis/sdks/py/commands/hash/hset
Write one or more fields to a hash.
## Arguments
The key of the hash.
Field to set
Value to set
An object of fields and their values.
## Response
The number of fields that were added.
```py Single
# Set a single field
assert redis.hset("myhash", "field1", "Hello") == 1
```
```py Multiple
# Set multiple fields
assert redis.hset("myhash", values={
"field1": "Hello",
"field2": "World"
}) == 2
```
# HSETNX
Source: https://upstash.com/docs/redis/sdks/py/commands/hash/hsetnx
Write a field to a hash but only if the field does not exist.
## Arguments
The key of the hash.
The name of the field.
The value to set.
## Response
`True` if the field was set, `False` if it already existed.
```py Example
assert redis.hsetnx("myhash", "field1", "Hello") == True
assert redis.hsetnx("myhash", "field1", "World") == False
```
# HSTRLEN
Source: https://upstash.com/docs/redis/sdks/py/commands/hash/hstrlen
Returns the string length of a value in a hash.
## Arguments
The key of the hash.
The name of the field.
## Response
`0` if the hash or field does not exist. Otherwise the length of the string.
```py Example
length = redis.hstrlen("key", "field")
```
# HTTL
Source: https://upstash.com/docs/redis/sdks/py/commands/hash/httl
Retrieves the remaining time-to-live (TTL) for field(s) in a hash in seconds.
## Arguments
The key of the hash.
The field or list of fields to retrieve the TTL for.
## Response
A list of integers representing the remaining TTL in seconds for each field.
* `-2` if the field does not exist in the hash or if the key doesn't exist.
* `-1` if the field exists but has no associated expiration.
For more details, see [HTTL documentation](https://redis.io/commands/httl).
```py Example
redis.hset(hash_name, field, value)
redis.hexpire(hash_name, field, 10)
assert redis.httl(hash_name, field) == [9]
```
# HVALS
Source: https://upstash.com/docs/redis/sdks/py/commands/hash/hvals
Returns all values in the hash stored at key.
## Arguments
The key of the hash.
## Response
All values in the hash, or an empty list when key does not exist.
```py Example
redis.hset("myhash", values={
"field1": "Hello",
"field2": "World"
})
assert redis.hvals("myhash") == ["Hello", "World"]
```
# JSON.ARRAPPEND
Source: https://upstash.com/docs/redis/sdks/py/commands/json/arrappend
Append values to the array at path in the JSON document at key.
To specify a string as an array value to append, wrap the quoted string with an additional set of single quotes. Example: '"silver"'.
## Arguments
The key of the json entry.
The path of the array.
One or more values to append to the array.
## Response
The length of the array after the appending.
```py Example
redis.json.arrappend("key", "$.path.to.array", "a")
```
# JSON.ARRINDEX
Source: https://upstash.com/docs/redis/sdks/py/commands/json/arrindex
Search for the first occurrence of a JSON value in an array.
## Arguments
The key of the json entry.
The path of the array.
The value to search for.
The start index.
The stop index.
## Response
The index of the first occurrence of the value in the array, or -1 if not found.
```py Example
index = redis.json.arrindex("key", "$.path.to.array", "a")
```
# JSON.ARRINSERT
Source: https://upstash.com/docs/redis/sdks/py/commands/json/arrinsert
Insert the json values into the array at path before the index (shifts to the right).
## Arguments
The key of the json entry.
The path of the array.
The index where to insert the values.
One or more values to append to the array.
## Response
The length of the array after the insertion.
```py Example
length = redis.json.arrinsert("key", "$.path.to.array", 2, "a", "b")
```
# JSON.ARRLEN
Source: https://upstash.com/docs/redis/sdks/py/commands/json/arrlen
Report the length of the JSON array at `path` in `key`.
## Arguments
The key of the json entry.
The path of the array.
## Response
The length of the array.
```py Example
length = redis.json.arrlen("key", "$.path.to.array")
```
# JSON.ARRPOP
Source: https://upstash.com/docs/redis/sdks/py/commands/json/arrpop
Remove and return an element from the index in the array. By default the last element from an array is popped.
## Arguments
The key of the json entry.
The path of the array.
The index of the element to pop.
## Response
The popped element or null if the array is empty.
```py Example
element = redis.json.arrpop("key", "$.path.to.array")
```
```py First
firstElement = redis.json.arrpop("key", "$.path.to.array", 0)
```
# JSON.ARRTRIM
Source: https://upstash.com/docs/redis/sdks/py/commands/json/arrtrim
Trim an array so that it contains only the specified inclusive range of elements.
## Arguments
The key of the json entry.
The path of the array.
The start index of the range.
The stop index of the range.
## Response
The length of the array after the trimming.
```py Example
length = redis.json.arrtrim("key", "$.path.to.array", 2, 10)
```
# JSON.CLEAR
Source: https://upstash.com/docs/redis/sdks/py/commands/json/clear
Clear container values (arrays/objects) and set numeric values to 0.
## Arguments
The key of the json entry.
The path to clear
## Response
How many keys cleared from the objects.
```py Example
redis.json.clear("key")
```
```py With path
redis.json.clear("key", "$.my.key")
```
# JSON.DEL
Source: https://upstash.com/docs/redis/sdks/py/commands/json/del
Delete a key from a JSON document.
## Arguments
The key of the json entry.
The path to delete
## Response
How many paths were deleted.
```py Example
redis.json.del("key", "$.path.to.value")
```
# JSON.FORGET
Source: https://upstash.com/docs/redis/sdks/py/commands/json/forget
Delete a key from a JSON document.
## Arguments
The key of the json entry.
The path to forget.
## Response
How many paths were deleted.
```py Example
redis.json.forget("key", "$.path.to.value")
```
# JSON.GET
Source: https://upstash.com/docs/redis/sdks/py/commands/json/get
Get a single value from a JSON document.
## Arguments
The key of the json entry.
One or more paths to retrieve from the JSON document.
## Response
The value at the specified path or `null` if the path does not exist.
```py Example
value = redis.json.get("key", "$.path.to.somewhere")
```
# JSON.MERGE
Source: https://upstash.com/docs/redis/sdks/py/commands/json/merge
Merges the JSON value at path in key with the provided value.
## Arguments
The key of the json entry.
The path of the value to set.
The value to merge with.
## Response
Returns true if the merge was successful.
```py Example
redis.json.merge("key", "$.path.to.value", {"new": "value"})
```
# JSON.MGET
Source: https://upstash.com/docs/redis/sdks/py/commands/json/mget
Get the same path from multiple JSON documents.
## Arguments
One or more keys of JSON documents.
The path to get from the JSON document.
## Response
The values at the specified path or `null` if the path does not exist.
```py Example
values = redis.json.mget(["key1", "key2"], "$.path.to.somewhere")
```
# JSON.MSET
Source: https://upstash.com/docs/redis/sdks/py/commands/json/mset
Sets multiple JSON values at multiple paths in multiple keys.
## Arguments
A list of tuples where each tuple contains a key, a path, and a value.
## Response
Returns true if the operation was successful.
```py Example
redis.json.mset([(key, "$.path", value), (key2, "$.path2", value2)])
```
# JSON.NUMINCRBY
Source: https://upstash.com/docs/redis/sdks/py/commands/json/numincrby
Increment the number value stored at `path` by number.
## Arguments
The key of the json entry.
The path of the number.
The number to increment by.
## Response
The new value after incrementing
```py Example
newValue = redis.json.numincrby("key", "$.path.to.value", 2)
```
# JSON.NUMMULTBY
Source: https://upstash.com/docs/redis/sdks/py/commands/json/nummultby
Multiply the number value stored at `path` by number.
## Arguments
The key of the json entry.
The path of the number.
The number to multiply by.
## Response
The new value after multiplying
```py Example
newValue = redis.json.nummultby("key", "$.path.to.value", 2)
```
# JSON.OBJKEYS
Source: https://upstash.com/docs/redis/sdks/py/commands/json/objkeys
Return the keys in the object that`s referenced by path.
## Arguments
The key of the json entry.
The path of the object.
## Response
The keys of the object at the path.
```py Example
keys = redis.json.objkeys("key", "$.path")
```
# JSON.OBJLEN
Source: https://upstash.com/docs/redis/sdks/py/commands/json/objlen
Report the number of keys in the JSON object at `path` in `key`.
## Arguments
The key of the json entry.
The path of the object.
## Response
The number of keys in the objects.
```py Example
lengths = redis.json.objlen("key", "$.path")
```
# JSON.RESP
Source: https://upstash.com/docs/redis/sdks/py/commands/json/resp
Return the value at the path in Redis serialization protocol format.
## Arguments
The key of the json entry.
The path of the object.
## Response
Return the value at the path in Redis serialization protocol format.
```py Example
resp = redis.json.resp("key", "$.path")
```
# JSON.SET
Source: https://upstash.com/docs/redis/sdks/py/commands/json/set
Set the JSON value at path in key.
## Arguments
The key of the json entry.
The path of the value to set.
The value to set.
Sets the value at path only if it does not exist.
Sets the value at path only if it does exist.
## Response
Returns true if the value was set.
```py Example
redis.json.set(key, "$.path", value)
```
```py NX
value = ...
redis.json.set(key, "$.path", value, nx=true)
```
```py XX
value = ...
redis.json.set(key, "$.path", value, xx=true)
```
# JSON.STRAPPEND
Source: https://upstash.com/docs/redis/sdks/py/commands/json/strappend
Append the json-string values to the string at path.
## Arguments
The key of the json entry.
The path of the string.
The value to append to the existing string.
## Response
The length of the string after the appending.
```py Example
redis.json.strappend("key", "$.path.to.str", "abc")
```
# JSON.STRLEN
Source: https://upstash.com/docs/redis/sdks/py/commands/json/strlen
Report the length of the JSON String at path in key
## Arguments
The key of the json entry.
The path of the string.
## Response
The length of the string at the path.
```py Example
redis.json.strlen("key", "$.path.to.str")
```
# JSON.TOGGLE
Source: https://upstash.com/docs/redis/sdks/py/commands/json/toggle
Toggle a boolean value stored at `path`.
## Arguments
The key of the json entry.
The path of the boolean.
## Response
The new value of the boolean.
```py Example
bool = redis.json.toggle("key", "$.path.to.bool")
```
# JSON.TYPE
Source: https://upstash.com/docs/redis/sdks/py/commands/json/type
Report the type of JSON value at `path`.
## Arguments
The key of the json entry.
The path of the value.
## Response
The type of the value at `path` or `null` if the value does not exist.
```py Example
myType = redis.json.type("key", "$.path.to.value")
```
# LINDEX
Source: https://upstash.com/docs/redis/sdks/py/commands/list/lindex
Returns the element at index index in the list stored at key.
The index is zero-based, so 0 means the first element, 1 the second element and so on. Negative indices can be used to designate elements starting at the tail of the list.
## Arguments
The key of the list.
The index of the element to return, zero-based.
## Response
The value of the element at index index in the list. If the index is out of range, `None` is returned.
```py Example
redis.rpush("key", "a", "b", "c")
assert redis.lindex("key", 0) == "a"
```
# LINSERT
Source: https://upstash.com/docs/redis/sdks/py/commands/list/linsert
Insert an element before or after another element in a list
## Arguments
The key of the list.
Whether to insert the element before or after pivot.
The element to insert before or after.
The element to insert.
## Response
The list length after insertion, `0` when the list doesn't exist or `-1` when pivot was not found.
```py Example
redis.rpush("key", "a", "b", "c")
redis.linsert("key", "before", "b", "x")
```
# LLEN
Source: https://upstash.com/docs/redis/sdks/py/commands/list/llen
Returns the length of the list stored at key.
## Arguments
The key of the list.
## Response
The length of the list at key.
```py Example
redis.rpush("key", "a", "b", "c")
assert redis.llen("key") == 3
```
# LMOVE
Source: https://upstash.com/docs/redis/sdks/py/commands/list/lmove
Move an element from one list to another.
## Arguments
The key of the source list.
The key of the destination list.
The side of the source list from which the element was popped.
The side of the destination list to which the element was pushed.
## Response
The element that was moved.
```py Example
redis.rpush("source", "one", "two", "three")
redis.lpush("destination", "four", "five", "six")
assert redis.lmove("source", "destination", "RIGHT", "LEFT") == "three"
assert redis.lrange("source", 0, -1) == ["one", "two"]
```
# LPOP
Source: https://upstash.com/docs/redis/sdks/py/commands/list/lpop
Remove and return the first element(s) of a list
## Arguments
The key of the list.
How many elements to pop. If not specified, a single element is popped.
## Response
The popped element(s). If `count` was specified, an array of elements is
returned, otherwise a single element is returned. If the list is empty, `None`
is returned.
```py Single
redis.rpush("mylist", "one", "two", "three")
assert redis.lpop("mylist") == "one"
```
```py Multiple
redis.rpush("mylist", "one", "two", "three")
assert redis.lpop("mylist", 2) == ["one", "two"]
```
# LPOS
Source: https://upstash.com/docs/redis/sdks/py/commands/list/lpos
Returns the index of matching elements inside a list.
## Arguments
The key of the list.
The element to match.
Which match to return. 1 to return the first match, 2 to return the second match, and so on.
1 by default.
The maximum number of elements to match. If specified, an array of elements
is returned instead of a single element.
Limit the number of comparisons to perform.
## Response
The index of the matching element or an array of indexes if `count` is
specified.
```py Example
redis.rpush("key", "a", "b", "c");
assert redis.lpos("key", "b") == 1
```
```py With Rank
redis.rpush("key", "a", "b", "c", "b");
assert redis.lpos("key", "b", rank=2) == 3
```
```py With Count
redis.rpush("key", "a", "b", "b")
assert redis.lpos("key", "b", count=2) == [1, 2]
```
# LPUSH
Source: https://upstash.com/docs/redis/sdks/py/commands/list/lpush
Push an element at the head of the list.
## Arguments
The key of the list.
One or more elements to push at the head of the list.
## Response
The length of the list after the push operation.
```py Example
assert redis.lpush("mylist", "one", "two", "three") == 3
assert lrange("mylist", 0, -1) == ["three", "two", "one"]
```
# LPUSHX
Source: https://upstash.com/docs/redis/sdks/py/commands/list/lpushx
Push an element at the head of the list only if the list exists.
## Arguments
The key of the list.
One or more elements to push at the head of the list.
## Response
The length of the list after the push operation.
`0` if the list did not exist and thus no element was pushed.
```py Example
# Initialize the list
redis.lpush("mylist", "one")
assert redis.lpushx("mylist", "two", "three") == 3
assert lrange("mylist", 0, -1) == ["three", "two", "one"]
# Non existing key
assert redis.lpushx("non-existent-list", "one") == 0
```
# LRANGE
Source: https://upstash.com/docs/redis/sdks/py/commands/list/lrange
Returns the specified elements of the list stored at key.
## Arguments
The key of the list.
The starting index of the range to return.
Use negative numbers to specify offsets starting at the end of the list.
The ending index of the range to return.
Use negative numbers to specify offsets starting at the end of the list.
## Response
The list of elements in the specified range.
```py Example
redis.rpush("mylist", "one", "two", "three")
assert redis.lrange("mylist", 0, 1) == ["one", "two"]
assert redis.lrange("mylist", 0, -1) == ["one", "two", "three"]
```
# LREM
Source: https://upstash.com/docs/redis/sdks/py/commands/list/lrem
Remove the first `count` occurrences of an element from a list.
## Arguments
The key of the list.
How many occurrences of the element to remove.
The element to remove
## Response
The number of elements removed.
```py Example
redis.rpush("mylist", "one", "two", "three", "two", "one")
assert redis.lrem("mylist", 2, "two") == 2
assert redis.lrange("mylist", 0, -1) == ["one", "three", "one"]
```
# LSET
Source: https://upstash.com/docs/redis/sdks/py/commands/list/lset
Set a value at a specific index.
## Arguments
The key of the list.
At which index to set the value.
The value to set.
## Response
Returns `True` if the index was in range and the value was set.
```py Example
redis.rpush("mylist", "one", "two", "three")
assert redis.lset("mylist", 1, "Hello") == True
assert redis.lrange("mylist", 0, -1) == ["one", "Hello", "three"]
assert redis.lset("mylist", 5, "Hello") == False
assert redis.lrange("mylist", 0, -1) == ["one", "Hello", "three"]
```
# LTRIM
Source: https://upstash.com/docs/redis/sdks/py/commands/list/ltrim
Trim a list to the specified range
## Arguments
The key of the list.
The index of the first element to keep.
The index of the first element to keep.
## Response
Returns `True` if the list was trimmed, `False` otherwise.
```py Example
redis.rpush("mylist", "one", "two", "three")
assert redis.ltrim("mylist", 0, 1) == True
assert redis.lrange("mylist", 0, -1) == ["one", "two"]
```
# RPOP
Source: https://upstash.com/docs/redis/sdks/py/commands/list/rpop
Remove and return the last element(s) of a list
## Arguments
The key of the list.
How many elements to pop. If not specified, a single element is popped.
## Response
The popped element(s). If `count` was specified, an array of elements is
returned, otherwise a single element is returned. If the list is empty, `null`
is returned.
```py Single
redis.rpush("mylist", "one", "two", "three")
assert redis.rpop("mylist") == "three"
```
```py Multiple
redis.rpush("mylist", "one", "two", "three")
assert redis.rpop("mylist", 2) == ["three", "two"]
```
# RPUSH
Source: https://upstash.com/docs/redis/sdks/py/commands/list/rpush
Push an element at the end of the list.
## Arguments
The key of the list.
One or more elements to push at the end of the list.
## Response
The length of the list after the push operation.
```py Example
assert redis.rpush("mylist", "one", "two", "three") == 3
assert lrange("mylist", 0, -1) == ["one", "two", "three"]
```
# RPUSHX
Source: https://upstash.com/docs/redis/sdks/py/commands/list/rpushx
Push an element at the end of the list only if the list exists.
## Arguments
The key of the list.
One or more elements to push at the end of the list.
## Response
The length of the list after the push operation.
`0` if the list did not exist and thus no element was pushed.
```py Example
assert redis.rpushx("mylist", "one", "two", "three") == 3
assert lrange("mylist", 0, -1) == ["one", "two", "three"]
# Non existing key
assert redis.rpushx("non-existent-list", "one") == 0
```
# Overview
Source: https://upstash.com/docs/redis/sdks/py/commands/overview
Available Commands in upstash-redis
Echo the given string.
Ping the server.
Count set bits in a string.
Perform bitwise operations between strings.
Perform bitwise operations between strings.
Find first bit set or clear in a string.
Returns the bit value at offset in the string value stored at key.
Sets or clears the bit at offset in the string value stored at key.
Delete one or multiple keys.
Determine if a key exists.
Set a key's time to live in seconds.
Set the expiration for a key as a UNIX timestamp.
Find all keys matching the given pattern.
Remove the expiration from a key.
Set a key's time to live in milliseconds.
Set the expiration for a key as a UNIX timestamp specified in milliseconds.
Get the time to live for a key in milliseconds.
Return a random key from the keyspace.
Rename a key.
Rename a key, only if the new key does not exist.
{/*
Create a key using the provided serialized value, previously obtained using DUMP.
*/}
Incrementally iterate the keys space.
{/*
Sort the elements in a list, set or sorted set.
*/}
Alters the last access time of a key(s). Returns the number of existing keys specified.
Get the time to live for a key.
Determine the type stored at key.
Delete one or more keys.
Publish messages to many clients
Append a value to a string stored at key.
Decrement the integer value of a key by one.
Decrement the integer value of a key by the given number.
Get the value of a key.
Get the value of a key and delete the key.
Get a substring of the string stored at a key.
Set the string value of a key and return its old value.
Increment the integer value of a key by one.
Increment the integer value of a key by the given amount.
Increment the float value of a key by the given amount.
Get the values of all the given keys.
Set multiple keys to multiple values.
Set multiple keys to multiple values, only if none of the keys exist.
Set the string value of a key.
Overwrite part of a string at key starting at the specified offset.
Get the length of the value stored in a key.
Run multiple commands in a transaction.
# PUBLISH
Source: https://upstash.com/docs/redis/sdks/py/commands/pubsub/publish
Publish a message to a channel
## Arguments
The channel to publish to.
The message to publish.
## Response
The number of clients who received the message.
```py Example
listeners = redis.publish("my-topic", "my-message")
```
# EVAL
Source: https://upstash.com/docs/redis/sdks/py/commands/scripts/eval
Evaluate a Lua script server side.
## Arguments
The lua script to run.
All of the keys accessed in the script
All of the arguments you passed to the script
## Response
The result of the script.
```py Example
script = """
local value = redis.call("GET", KEYS[1])
return value
"""
redis.set("mykey", "Hello")
assert redis.eval(script, keys=["mykey"]) == "Hello"
```
```py Accepting arguments
assert redis.eval("return ARGV[1]", args=["Hello"]) == "Hello"
```
# EVAL_RO
Source: https://upstash.com/docs/redis/sdks/py/commands/scripts/eval_ro
Evaluate a read-only Lua script server side.
## Arguments
The read-only lua script to run.
All of the keys accessed in the script
All of the arguments you passed to the script
## Response
The result of the script.
```py Example
script = """
local value = redis.call("GET", KEYS[1])
return value
"""
redis.set("mykey", "Hello")
assert redis.eval_ro(script, keys=["mykey"]) == "Hello"
```
```py Accepting arguments
assert redis.eval_ro("return ARGV[1]", args=["Hello"]) == "Hello"
```
# EVALSHA
Source: https://upstash.com/docs/redis/sdks/py/commands/scripts/evalsha
Evaluate a cached Lua script server side.
`EVALSHA` is like `EVAL` but instead of sending the script over the wire every time, you reference the script by its SHA1 hash. This is useful for caching scripts on the server side.
## Arguments
The sha1 hash of the script.
All of the keys accessed in the script
All of the arguments you passed to the script
## Response
The result of the script.
```py Example
result = redis.evalsha("fb67a0c03b48ddbf8b4c9b011e779563bdbc28cb", args=["hello"])
assert result = "hello"
```
# EVALSHA_RO
Source: https://upstash.com/docs/redis/sdks/py/commands/scripts/evalsha_ro
Evaluate a cached read-only Lua script server side.
`EVALSHA_RO` is like `EVAL_RO` but instead of sending the script over the wire every time, you reference the script by its SHA1 hash. This is useful for caching scripts on the server side.
## Arguments
The sha1 hash of the read-only script.
All of the keys accessed in the script
All of the arguments you passed to the script
## Response
The result of the script.
```py Example
result = redis.evalsha_ro("fb67a0c03b48ddbf8b4c9b011e779563bdbc28cb", args=["hello"])
assert result = "hello"
```
# SCRIPT EXISTS
Source: https://upstash.com/docs/redis/sdks/py/commands/scripts/script_exists
Check if scripts exist in the script cache.
## Arguments
The sha1 of the scripts to check.
## Response
A list of booleans indicating if the script exists in the script cache.
```py Example
# Script 1 exists
# Script 0 does not
await redis.scriptExists("", "") == [1, 0]
```
# SCRIPT FLUSH
Source: https://upstash.com/docs/redis/sdks/py/commands/scripts/script_flush
Removes all scripts from the script cache.
## Arguments
Whether to perform the flush asynchronously or synchronously.
```py Example
redis.script_flush(flush_type="ASYNC")
```
# SCRIPT LOAD
Source: https://upstash.com/docs/redis/sdks/py/commands/scripts/script_load
Load the specified Lua script into the script cache.
## Arguments
The script to load.
## Response
The sha1 of the script.
```py Example
sha1 = redis.script_load("return 1")
assert redis.evalsha(sha1) == 1
```
# DBSIZE
Source: https://upstash.com/docs/redis/sdks/py/commands/server/dbsize
Count the number of keys in the database.
## Arguments
This command has no arguments
## Response
The number of keys in the database
```py Example
redis.dbsize()
```
# FLUSHALL
Source: https://upstash.com/docs/redis/sdks/py/commands/server/flushall
Deletes all keys permanently. Use with caution!
## Arguments
Whether to perform the operation asynchronously.
Defaults to synchronous.
```py Sync
redis.flushall()
```
```py Async
redis.flushall(flush_type="ASYNC")
```
# FLUSHDB
Source: https://upstash.com/docs/redis/sdks/py/commands/server/flushdb
Deletes all keys permanently. Use with caution!
## Arguments
Whether to perform the operation asynchronously.
Defaults to synchronous.
```py Sync
redis.flushall()
```
```py Async
redis.flushall(flush_type="ASYNC")
```
# SADD
Source: https://upstash.com/docs/redis/sdks/py/commands/set/sadd
Adds one or more members to a set.
## Arguments
The key of the set.
One or more members to add to the set.
## Response
The number of elements that were added to the set, not including all the elements already present in the set.
```py Example
assert redis.sadd("key", "a", "b", "c") == 3
```
# SCARD
Source: https://upstash.com/docs/redis/sdks/py/commands/set/scard
Return how many members are in a set
## Arguments
The key of the set.
## Response
How many members are in the set.
```py Example
redis.sadd("key", "a", "b", "c");
assert redis.scard("key") == 3
```
# SDIFF
Source: https://upstash.com/docs/redis/sdks/py/commands/set/sdiff
Return the difference between sets
## Arguments
The keys of the sets to perform the difference operation on.
## Response
The resulting set.
```py Example
redis.sadd("set1", "a", "b", "c");
redis.sadd("set2", "c", "d", "e");
assert redis.sdiff("set1", "set2") == {"a", "b"}
```
# SDIFFSTORE
Source: https://upstash.com/docs/redis/sdks/py/commands/set/sdiffstore
Write the difference between sets to a new set
## Arguments
The key of the set to store the resulting set in.
The keys of the sets to perform the difference operation on.
## Response
The number of elements in the resulting set.
```py Example
redis.sadd("key1", "a", "b", "c")
redis.sadd("key2", "c", "d", "e")
# Store the result in a new set
assert redis.sdiffstore("res", "key1", "key2") == 2
assert redis.smembers("set") == {"a", "b"}
```
# SINTER
Source: https://upstash.com/docs/redis/sdks/py/commands/set/sinter
Return the intersection between sets
## Arguments
The keys of the sets to perform the intersection operation on.
## Response
The resulting set.
```py Example
redis.sadd("set1", "a", "b", "c");
redis.sadd("set2", "c", "d", "e");
assert redis.sinter("set1", "set2") == {"c"}
```
# SINTER
Source: https://upstash.com/docs/redis/sdks/py/commands/set/sinterstore
Return the intersection between sets and store the resulting set in a key
## Arguments
The key of the set to store the resulting set in.
The keys of the sets to perform the intersection operation on.
## Response
The number of elements in the resulting set.
```py Example
redis.sadd("set1", "a", "b", "c");
redis.sadd("set2", "c", "d", "e");
assert redis.sinter("destination", "set1", "set2") == 1
```
# SISMEMBER
Source: https://upstash.com/docs/redis/sdks/py/commands/set/sismember
Check if a member exists in a set
## Arguments
The key of the set to check.
The member to check for.
## Response
`True` if the member exists in the set, `False` if not.
```py Example
redis.sadd("set", "a", "b", "c")
assert redis.sismember("set", "a") == True
```
# SMEMBERS
Source: https://upstash.com/docs/redis/sdks/py/commands/set/smembers
Return all the members of a set
## Arguments
The key of the set.
## Response
The members of the set.
```py Example
redis.sadd("set", "a", "b", "c");
assert redis.smembers("set") == {"a", "b", "c"}
```
# SMISMEMBER
Source: https://upstash.com/docs/redis/sdks/py/commands/set/smismember
Check if multiple members exist in a set
## Arguments
The key of the set to check.
The members to check
## Response
An array of `True` and `False` values.
`True` if the member exists in the set, `False` if not.
```py Example
redis.sadd("myset", "one", "two", "three")
assert redis.smismember("myset", "one", "four") == [True, False]
assert redis.smismember("myset", "four", "five") == [False, False]
```
# SMOVE
Source: https://upstash.com/docs/redis/sdks/py/commands/set/smove
Move a member from one set to another
## Arguments
The key of the set to move the member from.
The key of the set to move the member to.
The members to move
## Response
`True` if the member was moved, `False` if it was not.
```py Example
redis.sadd("src", "one", "two", "three")
redis.sadd("dest", "four")
assert redis.smove("src", "dest", "three") == True
assert redis.smembers("source") == {"one", "two"}
assert redis.smembers("destination") == {"three", "four"}
```
# SPOP
Source: https://upstash.com/docs/redis/sdks/py/commands/set/spop
Removes and returns one or more random members from a set.
## Arguments
The key of the set.
How many members to remove and return.
## Response
The popped member.
If `count` is specified, a set of members is returned.
```py Single
redis.sadd("myset", "one", "two", "three")
assert redis.spop("myset") in {"one", "two", "three"}
```
```py With Count
redis.sadd("myset", "one", "two", "three")
assert redis.spop("myset", 2) in {"one", "two", "three"}
```
# SRANDMEMBER
Source: https://upstash.com/docs/redis/sdks/py/commands/set/srandmember
Returns one or more random members from a set.
## Arguments
The key of the set.
How many members to return.
## Response
The random member.
If `count` is specified, an array of members is returned.
```py Single
redis.sadd("myset", "one", "two", "three")
assert redis.srandmember("myset") in {"one", "two", "three"}
```
```py With Count
redis.sadd("myset", "one", "two", "three")
assert redis.srandmember("myset", 2) in {"one", "two", "three"}
```
# SREM
Source: https://upstash.com/docs/redis/sdks/py/commands/set/srem
Remove one or more members from a set
## Arguments
The key of the set to remove the member from.
One or more members to remove from the set.
## Response
How many members were removed
```py Example
redis.sadd("myset", "one", "two", "three")
assert redis.srem("myset", "one", "four") == 1
```
# SSCAN
Source: https://upstash.com/docs/redis/sdks/py/commands/set/sscan
Scan a set
## Arguments
The key of the set.
The cursor, use `0` in the beginning and then use the returned cursor for subsequent calls.
Glob-style pattern to filter by members.
Number of members to return per call.
## Response
The new cursor and the members.
If the new cursor is `0` the iteration is complete.
```py Example
# Get all members of a set.
cursor = 0
results = set()
while True:
cursor, keys = redis.sscan("myset", cursor, match="*")
results.extend(keys)
if cursor == 0:
break
```
# SUNION
Source: https://upstash.com/docs/redis/sdks/py/commands/set/sunion
Return the union between sets
## Arguments
The keys of the sets to perform the union operation on.
## Response
The resulting set
```py Example
redis.sadd("key1", "a", "b", "c")
redis.sadd("key2", "c", "d", "e")
assert redis.sunion("key1", "key2") == {"a", "b", "c", "d", "e"}
```
# SUNIONSTORE
Source: https://upstash.com/docs/redis/sdks/py/commands/set/sunionstore
Return the union between sets and store the resulting set in a key
## Arguments
The key of the set to store the resulting set in.
The keys of the sets to perform the union operation on.
## Response
The members of the resulting set.
```py Example
redis.sadd("set1", "a", "b", "c");
redis.sadd("set2", "c", "d", "e");
redis.sunionstore("destination", "set1", "set2")
```
# XADD
Source: https://upstash.com/docs/redis/sdks/py/commands/stream/xadd
Appends one or more new entries to a stream.
## Arguments
The key to of the stream.
The stream entry ID. If `*` is passed, a new ID will be generated
automatically.
Key-value data to be appended to the stream.
Prevent creating the stream if it does not exist.
The trim mode.
{" "}
The threshold value for the trim mode.
The comparison operator for the trim mode.
Limit how many entries will be trimmed at most.
## Response
The ID of the newly added entry.
```py Example
redis.xadd(key, "*", { name: "John Doe", age: 30 })
```
```py Trimming
redis.xadd(key, "*", { name: "John Doe", age: 30 }, {
trim: {
type: "MAXLEN",
threshold: 1000,
comparison: "=",
},
})
```
# XRANGE
Source: https://upstash.com/docs/redis/sdks/py/commands/stream/xrange
Returns stream entries matching a given range of IDs.
## Arguments
The key to of the stream.
The stream entry ID to start from.
The stream entry ID to end at.
The maximum number of entries to return.
## Response
An object of stream entries, keyed by their stream ID
```py Example
entries = redis.xrange(key, "-", "+")
print(entries)
# {
# "1548149259438-0": {
# "field1": "value1",
# "field2": "value2"
# },
# "1548149259438-1": {
# "field1": "value3",
# "field2": "value4"
# }
# }
```
# APPEND
Source: https://upstash.com/docs/redis/sdks/py/commands/string/append
Append a value to a string stored at key.
## Arguments
The key to get.
The value to append.
## Response
How many characters were added to the string.
```py Example
redis.set("key", "Hello")
assert redis.append("key", " World") == 11
assert redis.get("key") == "Hello World"
```
# DECR
Source: https://upstash.com/docs/redis/sdks/py/commands/string/decr
Decrement the integer value of a key by one
If a key does not exist, it is initialized as 0 before performing the operation. An error is returned if the key contains a value of the wrong type or contains a string that can not be represented as integer.
## Arguments
The key to decrement.
## Response
The value at the key after the decrementing.
```py Example
redis.set("key", 6)
assert redis.decr("key") == 5
```
# DECRBY
Source: https://upstash.com/docs/redis/sdks/py/commands/string/decrby
Decrement the integer value of a key by a given number.
If a key does not exist, it is initialized as 0 before performing the operation. An error is returned if the key contains a value of the wrong type or contains a string that can not be represented as integer.
## Arguments
The key to decrement.
The amount to decrement by.
## Response
The value at the key after the decrementing.
```py Example
redis.set("key", 6)
assert redis.decrby("key", 4) == 2
```
# GET
Source: https://upstash.com/docs/redis/sdks/py/commands/string/get
Return the value of the specified key or `None` if the key doesn't exist.
## Arguments
The key to get.
## Response
The response is the value stored at the key or `None` if the key doesn't exist.
```py Example
redis.set("key", "value")
assert redis.get("key") == "value"
```
# GETDEL
Source: https://upstash.com/docs/redis/sdks/py/commands/string/getdel
Return the value of the specified key and delete the key.
## Arguments
The key to get.
## Response
The response is the value stored at the key or `None` if the key doesn't exist.
```py Example
redis.set("key", "value")
assert redis.getdel("key") == "value"
assert redis.get("key") == None
```
# GETRANGE
Source: https://upstash.com/docs/redis/sdks/py/commands/string/getrange
Return a substring of value at the specified key.
## Arguments
The key to get.
The start index of the substring.
The end index of the substring.
## Response
The substring.
```py Example
redis.set("key", "Hello World")
assert redis.getrange("key", 0, 4) == "Hello"
```
# GETSET
Source: https://upstash.com/docs/redis/sdks/py/commands/string/getset
Return the value of the specified key and replace it with a new value.
## Arguments
The key to get.
The new value to store.
## Response
The response is the value stored at the key or `None` if the key doesn't exist.
```py Example
redis.set("key", "old-value")
assert redis.getset("key", "newvalue") == "old-value"
```
# INCR
Source: https://upstash.com/docs/redis/sdks/py/commands/string/incr
Increment the integer value of a key by one
If a key does not exist, it is initialized as 0 before performing the operation. An error is returned if the key contains a value of the wrong type or contains a string that can not be represented as integer.
## Arguments
The key to increment.
## Response
The value at the key after the incrementing.
```py Example
redis.set("key", 6)
assert redis.incr("key") == 7
```
# INCRBY
Source: https://upstash.com/docs/redis/sdks/py/commands/string/incrby
Increment the integer value of a key by a given number.
If a key does not exist, it is initialized as 0 before performing the operation. An error is returned if the key contains a value of the wrong type or contains a string that can not be represented as integer.
## Arguments
The key to decrement.
The amount to increment by.
## Response
The value at the key after the incrementing.
```py Example
redis.set("key", 6)
assert redis.incrby("key", 4) == 10
```
# INCRBYFLOAT
Source: https://upstash.com/docs/redis/sdks/py/commands/string/incrbyfloat
Increment the float value of a key by a given number.
If a key does not exist, it is initialized as 0 before performing the operation. An error is returned if the key contains a value of the wrong type or contains a string that can not be represented as integer.
## Arguments
The key to decrement.
The amount to increment by.
## Response
The value at the key after the incrementing.
```py Example
redis.set("key", 6)
# returns 10.5
redis.incrbyfloat("key", 4,5)
```
# MGET
Source: https://upstash.com/docs/redis/sdks/py/commands/string/mget
Load multiple keys from Redis in one go.
For billing purposes, this counts as a single command.
## Arguments
Multiple keys to load from Redis.
## Response
An array of values corresponding to the keys passed in. If a key doesn't exist, the value will be `None`.
```py Example
redis.set("key1", "value1")
redis.set("key2", "value2")
assert redis.mget("key1", "key2") == ["value1", "value2"]
```
# MSET
Source: https://upstash.com/docs/redis/sdks/py/commands/string/mset
Set multiple keys in one go.
For billing purposes, this counts as a single command.
## Arguments
An object where the keys are the keys to set, and the values are the values to set.
## Response
`True` if the operation succeeded.
```py Example
redis.mset({
"key1": "value1",
"key2": "value2"
})
```
# MSETNX
Source: https://upstash.com/docs/redis/sdks/py/commands/string/msetnx
Set multiple keys in one go unless they exist already.
For billing purposes, this counts as a single command.
## Arguments
An object where the keys are the keys to set, and the values are the values to set.
## Response
`1` if all keys were set, `0` if at least one key was not set.
```py Example
redis.msetnx({
key1: 1,
key2: "hello",
key3: { a: 1, b: "hello" },
})
```
# SET
Source: https://upstash.com/docs/redis/sdks/py/commands/string/set
Set a key to hold a string value.
## Arguments
The key
The value, if this is not a string, we will use `JSON.stringify` to convert it
to a string.
Instead of returning `True`, this will cause the command to return the old
value stored at key, or `None` when key did not exist.
Sets an expiration (in seconds) to the key.
Sets an expiration (in milliseconds) to the key.
Set the UNIX timestamp in seconds until the key expires.
Set the UNIX timestamp in milliseconds until the key expires.
Keeps the old expiration if the key already exists.
Only set the key if it does not already exist.
Only set the key if it already exists.
## Response
`True` if the key was set.
If `get` is specified, this will return the old value stored at key, or `None` when
the key did not exist.
```py Basic
assert redis.set("key", "value") == True
assert redis.get("key") == "value"
```
```py With nx and xx
# Only set the key if it does not already exist.
assert redis.set("key", "value", nx=True) == False
# Only set the key if it already exists.
assert redis.set("key", "value", xx=True) == True
```
```py With expiration
# Set the key to expire in 10 seconds.
assert redis.set("key", "value", ex=10) == True
# Set the key to expire in 10000 milliseconds.
assert redis.set("key", "value", px=10000) == True
```
```py With old value
# Get the old value stored at the key.
assert redis.set("key", "new-value", get=True) == "old-value"
```
# SETRANGE
Source: https://upstash.com/docs/redis/sdks/py/commands/string/setrange
Writes the value of key at offset.
The SETRANGE command in Redis is used to modify a portion of the value of a key by replacing a substring within the key's existing value. It allows you to update part of the string value associated with a specific key at a specified offset.
## Arguments
The name of the Redis key for which you want to modify the value.
The zero-based index in the value where you want to start replacing characters.
The new string that you want to insert at the specified offset in the existing value.
## Response
The length of the value after it was modified.
```py Example
redis.set("key", "Hello World")
assert redis.setrange("key", 6, "Redis") == 11
assert redis.get("key") == "Hello Redis"
```
# STRLEN
Source: https://upstash.com/docs/redis/sdks/py/commands/string/strlen
Return the length of a string stored at a key.
The \`STRLEN\`\` command in Redis is used to find the length of the string value associated with a key. In Redis, keys can be associated with various data types, and one of these data types is the "string." The STRLEN command specifically operates on keys that are associated with string values.
## Arguments
The name of the Redis key.
## Response
The length of the value.
```py Example
redis.set("key", "Hello World")
assert redis.strlen("key") == 11
```
# ZADD
Source: https://upstash.com/docs/redis/sdks/py/commands/zset/zadd
Add a member to a sorted set, or update its score if it already exists.
## Arguments
The key of the sorted set.
A dictionary of elements and their scores.
Only update elements that already exist. Never add elements.
Only add new elements. Never update elements.
Update scores if the new score is greater than the old score.
Update scores if the new score is less than the old score.
Return the number of elements changed instead.
When this option is specified `ZADD` acts like `ZINCRBY`. Only one score-element pair can be specified in this mode.
## Response
The number of elements added to the sorted sets, not including elements already existing for which the score was updated.
If `ch` was specified, the number of elements that were updated.
If `incr` was specified, the new score of `member`.
```py Simple
# Add three elements
assert redis.zadd("myset", {
"one": 1,
"two": 2,
"three": 3
}) == 3
# No element is added since "one" and "two" already exist
assert redis.zadd("myset", {
"one": 1,
"two": 2
}, nx=True) == 0
# New element is not added since it does not exist
assert redis.zadd("myset", {
"new-element": 1
}, xx=True) == 0
# Only "three" is updated since new score was greater
assert redis.zadd("myset", {
"three": 10, "two": 0
}, gt=True) == 1
# Only "three" is updated since new score was greater
assert redis.zadd("myset", {
"three": 10,
"two": 0
}, gt=True) == 1
```
# ZCARD
Source: https://upstash.com/docs/redis/sdks/py/commands/zset/zcard
Returns the number of elements in the sorted set stored at key.
## Arguments
The key to get.
## Response
The number of elements in the sorted set.
```py Example
redis.zadd("myset", {"one": 1, "two": 2, "three": 3})
assert redis.zcard("myset") == 3
```
# ZCOUNT
Source: https://upstash.com/docs/redis/sdks/py/commands/zset/zcount
Returns the number of elements in the sorted set stored at key filterd by score.
## Arguments
The key to get.
The minimum score to filter by.
Use `-inf` to effectively ignore this filter.
Use `(number` to exclude the value.
The maximum score to filter by.
Use `+inf` to effectively ignore this filter.
Use `(number` to exclude the value.
## Response
The number of elements where score is between min and max.
```py Example
redis.zadd("key",
{ score: 1, member: "one"},
{ score: 2, member: "two" },
)
elements = redis.zcount("key", "(1", "+inf")
print(elements); # 1
```
# ZDIFF
Source: https://upstash.com/docs/redis/sdks/py/commands/zset/zdiff
Returns the difference between sets.
## Arguments
The keys of the sets to compare.
Whether to include scores in the result.
## Response
The number of elements in the resulting set.
```py Simple
redis.zadd("key1", {"a": 1, "b": 2, "c": 3})
redis.zadd("key2", {"c": 3, "d": 4, "e": 5})
result = redis.zdiff(["key1", "key2"])
assert result == ["a", "b"]
```
```py With scores
redis.zadd("key1", {"a": 1, "b": 2, "c": 3})
redis.zadd("key2", {"c": 3, "d": 4, "e": 5})
result = redis.zdiff(["key1", "key2"], withscores=True)
assert result == [("a", 1), ("b", 2)]
```
# ZDIFFSTORE
Source: https://upstash.com/docs/redis/sdks/py/commands/zset/zdiffstore
Writes the difference between sets to a new key.
## Arguments
The key to write the difference to.
The keys to compare.
## Response
The number of elements in the resulting set.
```py Example
redis.zadd("key1", {"a": 1, "b": 2, "c": 3})
redis.zadd("key2", {"c": 3, "d": 4, "e": 5})
# a and b
assert redis.zdiffstore("dest", ["key1", "key2"]) == 2
```
# ZINCRBY
Source: https://upstash.com/docs/redis/sdks/py/commands/zset/zincrby
Increment the score of a member.
## Arguments
The key of the sorted set.
The increment to add to the score.
The member to increment.
## Response
The new score of `member` after the increment operation.
```py Example
redis.zadd("myset", {"one": 1, "two": 2, "three": 3})
assert redis.zincrby("myset", 2, "one") == 3
```
# ZINTER
Source: https://upstash.com/docs/redis/sdks/py/commands/zset/zinter
Returns the intersection between sets.
## Arguments
The keys of the sets to compare.
The weights to apply to the sets.
The aggregation function to apply to the sets.
Whether to include scores in the result.
## Response
The number of elements in the resulting set.
```py Simple
redis.zadd("key1", {"a": 1, "b": 2, "c": 3})
redis.zadd("key2", {"c": 3, "d": 4, "e": 5})
result = redis.zinter(["key1", "key2"])
assert result == ["c"]
```
```py Aggregation
redis.zadd("key1", {"a": 1, "b": 2, "c": 3})
redis.zadd("key2", {"a": 3, "b": 4, "c": 5})
result = redis.zinter(["key1", "key2"], withscores=True, aggregate="SUM")
assert result == [("a", 4), ("b", 6), ("c", 8)]
```
```py Weights
redis.zadd("key1", {"a": 1})
redis.zadd("key2", {"a": 1})
result = redis.zinter(["key1", "key2"],
withscores=True,
aggregate="SUM",
weights=[2, 3])
assert result == [("a", 5)]
```
# ZINTERSTORE
Source: https://upstash.com/docs/redis/sdks/py/commands/zset/zinterstore
Calculates the intersection of sets and stores the result in a key
## Arguments
The key to store the result in.
The keys of the sets to compare.
The weights to apply to the sets.
The aggregation function to apply to the sets.
Whether to include scores in the result.
## Response
## Response
The number of elements in the resulting set.
```py Simple
redis.zadd("key1", {"a": 1, "b": 2, "c": 3})
redis.zadd("key2", {"c": 3, "d": 4, "e": 5})
result = redis.zinterstore("dest", ["key1", "key2"])
assert result == 1
```
```py Aggregation
redis.zadd("key1", {"a": 1, "b": 2, "c": 3})
redis.zadd("key2", {"a": 3, "b": 4, "c": 5})
result = redis.zinterstore("dest", ["key1", "key2"], withscores=True, aggregate="SUM")
assert result == 3
```
```py Weights
redis.zadd("key1", {"a": 1})
redis.zadd("key2", {"a": 1})
result = redis.zinterstore("dest", ["key1", "key2"],
withscores=True,
aggregate="SUM",
weights=[2, 3])
assert result == 1
```
# ZLEXCOUNT
Source: https://upstash.com/docs/redis/sdks/py/commands/zset/zlexcount
Returns the number of elements in the sorted set stored at key filterd by lex.
## Arguments
The key to get.
The lower lexicographical bound to filter by.
Use `-` to disable the lower bound.
The upper lexicographical bound to filter by.
Use `+` to disable the upper bound.
## Response
The number of matched.
```py Example
redis.zadd("myset", {"a": 1, "b": 2, "c": 3})
assert redis.zlexcount("myset", "-", "+") == 3
```
# ZMSCORE
Source: https://upstash.com/docs/redis/sdks/py/commands/zset/zmscore
Returns the scores of multiple members.
## Arguments
The key of the sorted set.
## Response
The members of the sorted set.
```py Example
redis.zadd("myset", {"a": 1, "b": 2, "c": 3})
assert redis.zlexcount("myset", "-", "+") == 3
```
# ZPOPMAX
Source: https://upstash.com/docs/redis/sdks/py/commands/zset/zpopmax
Removes and returns up to count members with the highest scores in the sorted set stored at key.
## Arguments
The key of the sorted set
The number of members to pop
## Response
A list of tuples containing the popped members and their scores
```py Example
redis.zadd("myset", {"a": 1, "b": 2, "c": 3})
assert redis.zpopmax("myset") == [("c", 3)]
```
# ZPOPMIN
Source: https://upstash.com/docs/redis/sdks/py/commands/zset/zpopmin
Removes and returns up to count members with the lowest scores in the sorted set stored at key.
## Arguments
The key of the sorted set
The number of members to pop
## Response
A list of tuples containing the popped members and their scores
```py Example
redis.zadd("myset", {"a": 1, "b": 2, "c": 3})
assert redis.zpopmin("myset") == [("a", 1)]
```
# ZRANDMEMBER
Source: https://upstash.com/docs/redis/sdks/py/commands/zset/zrandmember
Returns one or more random members from a sorted set, optionally with their scores.
## Arguments
The key of the sorted set
The number of members to return
Whether to return the scores along with the members
## Response
The random member(s) from the sorted set
If no count is specified, a single member is returned. If count is specified, a list of members is returned.
If withscores, members are returned as a tuple of (member, score).
```py Example
redis.zadd("myset", {"one": 1, "two": 2, "three": 3})
# "one"
redis.zrandmember("myset")
# ["one", "three"]
redis.zrandmember("myset", 2)
```
# ZRANGE
Source: https://upstash.com/docs/redis/sdks/py/commands/zset/zrange
Returns the specified range of elements in the sorted set stored at key.
## Arguments
The key to get.
The minimum value to include.
The maximum value to include.
"-inf" and "+inf" are also valid values for the ranges
Whether to include the scores in the response.
Whether to reverse the order of the response.
If bylex
The offset to start from.
The number of elements to return.
## Response
The values in the specified range.
If `withscores` is true, the members will be tuples of the form `(member, score)`.
```py Example
redis.zadd("myset", {"a": 1, "b": 2, "c": 3})
assert redis.zrange("myset", 0, 1) == ["a", "b"]
```
```py Reverse
redis.zadd("myset", {"a": 1, "b": 2, "c": 3})
assert redis.zrange("myset", 0, 1, rev=True) == ["c", "b"]
```
```py Sorted
redis.zadd("myset", {"a": 1, "b": 2, "c": 3})
assert redis.zrange("myset", 0, 1, sortby="BYSCORE") == ["a", "b"]
```
```py With scores
redis.zadd("myset", {"a": 1, "b": 2, "c": 3})
assert redis.zrange("myset", 0, 1, withscores=True) == [("a", 1), ("b", 2)]
```
# ZRANK
Source: https://upstash.com/docs/redis/sdks/py/commands/zset/zrank
Returns the rank of a member
## Arguments
The key to get.
The member to get the rank of.
## Response
The rank of the member.
```py Example
redis.zadd("myset", {"a": 1, "b": 2, "c": 3})
assert redis.zrank("myset", "a") == 0
assert redis.zrank("myset", "d") == None
assert redis.zrank("myset", "b") == 1
assert redis.zrank("myset", "c") == 2
```
# ZREM
Source: https://upstash.com/docs/redis/sdks/py/commands/zset/zrem
Remove one or more members from a sorted set
## Arguments
The key of the sorted set
One or more members to remove
## Response
The number of members removed from the sorted set.
```py Single
redis.zadd("myset", {"one": 1, "two": 2, "three": 3})
assert redis.zrem("myset", "one", "four") == 1
```
# ZREMRANGEBYLEX
Source: https://upstash.com/docs/redis/sdks/py/commands/zset/zremrangebylex
Remove all members in a sorted set between the given lexicographical range.
## Arguments
The key of the sorted set
The minimum lexicographical value to remove.
The maximum lexicographical value to remove.
## Response
The number of elements removed from the sorted set.
```py Example
redis.zremrangebylex("key", "alpha", "omega")
```
# ZREMRANGEBYRANK
Source: https://upstash.com/docs/redis/sdks/py/commands/zset/zremrangebyrank
Remove all members in a sorted set between the given ranks.
## Arguments
The key of the sorted set
The minimum rank to remove.
The maximum rank to remove.
## Response
The number of elements removed from the sorted set.
```py Example
redis.zremrangebyrank("key", 4, 20)
```
# ZREMRANGEBYSCORE
Source: https://upstash.com/docs/redis/sdks/py/commands/zset/zremrangebyscore
Remove all members in a sorted set between the given scores.
## Arguments
The key of the sorted set
The minimum score to remove.
The maximum score to remove.
## Response
The number of elements removed from the sorted set.
```py Example
redis.zremrangebyscore("key", 2, 5)
```
# ZREVRANK
Source: https://upstash.com/docs/redis/sdks/py/commands/zset/zrevrank
Returns the rank of a member in a sorted set, with scores ordered from high to low.
## Arguments
The key to get.
The member to get the reverse rank of.
## Response
The reverse rank of the member.
```py Example
redis.zadd("myset", {"a": 1, "b": 2, "c": 3})
assert redis.zrevrank("myset", "a") == 2
```
# ZSCAN
Source: https://upstash.com/docs/redis/sdks/py/commands/zset/zscan
Scan a sorted set
Return a paginated list of members and their scores of an ordered set matching a pattern.
## Arguments
The key of the sorted set.
The cursor, use `0` in the beginning and then use the returned cursor for subsequent calls.
Glob-style pattern to filter by members.
Number of members to return per call.
## Response
The new cursor and keys as a tuple.
If the new cursor is `0` the iteration is complete.
```py Example
# Get all elements of an ordered set.
cursor = 0
results = []
while True:
cursor, keys = redis.zscan("myzset", cursor, match="*")
results.extend(keys)
if cursor == 0:
break
for key, score in results:
print(key, score)
```
# ZSCORE
Source: https://upstash.com/docs/redis/sdks/py/commands/zset/zscore
Returns the scores of a member.
## Arguments
The key to get.
## Response
A member of the sortedset.
```py Example
redis.zadd("myset", {"a": 1, "b": 2, "c": 3})
assert redis.zscore("myset", "a") == 1
```
# ZINTER
Source: https://upstash.com/docs/redis/sdks/py/commands/zset/zunion
Returns the intersection between sets.
## Arguments
The keys of the sets to compare.
The weights to apply to the sets.
The aggregation function to apply to the sets.
Whether to include scores in the result.
## Response
The number of elements in the resulting set.
```py Simple
redis.zadd("key1", {"a": 1, "b": 2, "c": 3})
redis.zadd("key2", {"c": 3, "d": 4, "e": 5})
result = redis.zunion(["key1", "key2"])
assert result == ["a", "b", "c", "d", "e"]
```
```py Aggregation
redis.zadd("key1", {"a": 1, "b": 2, "c": 3})
redis.zadd("key2", {"a": 3, "b": 4, "c": 5})
result = redis.zunion(["key1", "key2"], withscores=True, aggregate="SUM")
assert result == [("a", 4), ("b", 6), ("c", 8)]
```
```py Weights
redis.zadd("key1", {"a": 1})
redis.zadd("key2", {"a": 1})
result = redis.zunion(["key1", "key2"],
withscores=True,
aggregate="SUM",
weights=[2, 3])
assert result == [("a", 5)]
```
# ZUNIONSTORE
Source: https://upstash.com/docs/redis/sdks/py/commands/zset/zunionstore
Writes the union between sets to a new key.
## Arguments
The key to store the resulting set in.
The keys of the sets to compare.
The weights to apply to the sets.
The aggregation function to apply to the sets.
Whether to include scores in the result.
## Response
The number of elements in the resulting set.
```py Simple
redis.zadd("key1", {"a": 1, "b": 2, "c": 3})
redis.zadd("key2", {"c": 3, "d": 4, "e": 5})
result = redis.zunionstore(["key1", "key2"])
assert result == 5
```
```py Aggregation
redis.zadd("key1", {"a": 1, "b": 2, "c": 3})
redis.zadd("key2", {"a": 3, "b": 4, "c": 5})
result = redis.zunionstore(["key1", "key2"], withscores=True, aggregate="SUM")
assert result == [("a", 4), ("b", 6), ("c", 8)]
```
```py Weights
redis.zadd("key1", {"a": 1})
redis.zadd("key2", {"a": 1})
result = redis.zunionstore(["key1", "key2"],
withscores=True,
aggregate="SUM",
weights=[2, 3])
assert result == [("a", 5)]
```
# Features
Source: https://upstash.com/docs/redis/sdks/py/features
### BITFIELD and BITFIELD\_RO
One particular case is represented by these two chained commands, which are
available as functions that return an instance of the `BITFIELD` and,
respectively, `BITFIELD_RO` classes. Use the `execute` function to run the
commands.
```python
redis.bitfield("test_key") \
.incrby(encoding="i8", offset=100, increment=100) \
.overflow("SAT") \
.incrby(encoding="i8", offset=100, increment=100) \
.execute()
redis.bitfield_ro("test_key_2") \
.get(encoding="u8", offset=0) \
.get(encoding="u8", offset="#1") \
.execute()
```
### Custom commands
If you want to run a command that hasn't been implemented, you can use the
`execute` function of your client instance and pass the command as a `list`.
```python
redis.execute(["XLEN", "test_stream"])
```
# Encoding
Although Redis can store invalid JSON data, there might be problems with the
deserialization. To avoid this, the Upstash REST proxy is capable of encoding
the data as base64 on the server and then sending it to the client to be
decoded.
For very large data, this can add a few milliseconds in latency. So, if you're
sure that your data is valid JSON, you can set `rest_encoding` to `None`.
# Retry mechanism
upstash-redis has a fallback mechanism in case of network or API issues. By
default, if a request fails it'll retry once, 3 seconds after the error. If you
want to customize that, set `rest_retries` and `rest_retry_interval` (in
seconds).
# Pipelines & Transactions
If you want to submit commands in batches to reduce the number of roundtrips, you can utilize pipelining or
transactions. The difference between pipelines and transactions is that transactions are atomic: no other
command is executed during that transaction. In pipelines there is no such guarantee.
To use a pipeline, simply call the `pipeline` method:
```python
pipeline = redis.pipeline()
pipeline.set("foo", 1)
pipeline.incr("foo")
pipeline.get("foo")
result = pipeline.exec()
print(result)
# prints [True, 2, '2']
```
For transaction, use `mutli`:
```python
pipeline = redis.multi()
pipeline.set("foo", 1)
pipeline.incr("foo")
pipeline.get("foo")
result = pipeline.exec()
print(result)
# prints [True, 2, '2']
```
You can also chain the commands:
```python
pipeline = redis.pipeline()
pipeline.set("foo", 1).incr("foo").get("foo")
result = pipeline.exec()
print(result)
# prints [True, 2, '2']
```
# Getting Started
Source: https://upstash.com/docs/redis/sdks/py/gettingstarted
## Install
### PyPI
```bash
pip install upstash-redis
```
## Usage
To be able to use upstash-redis, you need to create a database on
[Upstash](https://console.upstash.com/) and grab `UPSTASH_REDIS_REST_URL` and
`UPSTASH_REDIS_REST_TOKEN` from the console.
```python
# for sync client
from upstash_redis import Redis
redis = Redis(url="UPSTASH_REDIS_REST_URL", token="UPSTASH_REDIS_REST_TOKEN")
# for async client
from upstash_redis.asyncio import Redis
redis = Redis(url="UPSTASH_REDIS_REST_URL", token="UPSTASH_REDIS_REST_TOKEN")
```
Or, if you want to automatically load the credentials from the environment:
```python
# for sync use
from upstash_redis import Redis
redis = Redis.from_env()
# for async use
from upstash_redis.asyncio import Redis
redis = Redis.from_env()
```
If you are in a serverless environment that allows it, it's recommended to
initialise the client outside the request handler to be reused while your
function is still hot.
Running commands might look like this:
```python
from upstash_redis import Redis
redis = Redis.from_env()
def main():
redis.set("a", "b")
print(redis.get("a"))
# or for async context:
from upstash_redis.asyncio import Redis
redis = Redis.from_env()
async def main():
await redis.set("a", "b")
print(await redis.get("a"))
```
# Overview
Source: https://upstash.com/docs/redis/sdks/py/overview
`upstash-redis` is a connectionless, HTTP-based Redis client for Python,
designed to be used in serverless and serverful environments such as:
* AWS Lambda
* Vercel Serverless
* Google Cloud Functions
* and other environments where HTTP is preferred over TCP.
Inspired by other Redis clients like
[@upstash/redis](https://github.com/upstash/upstash-redis) and
[redis-py](https://github.com/redis/redis-py), the goal of this SDK is to
provide a simple way to use Redis over the
[Upstash REST API](https://docs.upstash.com/redis/features/restapi).
The SDK is currently compatible with Python 3.8 and above.
You can find the Github Repository [here](https://github.com/upstash/redis-python).
# Ratelimiting Algorithms
Source: https://upstash.com/docs/redis/sdks/ratelimit-py/algorithms
## Fixed Window
This algorithm divides time into fixed durations/windows. For example each
window is 10 seconds long. When a new request comes in, the current time is used
to determine the window and a counter is increased. If the counter is larger
than the set limit, the request is rejected.
In fixed & sliding window algorithms, the reset time is based on fixed time boundaries (which depend on the period), not on when the first request was made. So two requests made right before the window ends still count toward the current window, and limits reset at the start of the next window.
### Pros
* Very cheap in terms of data size and computation
* Newer requests are not starved due to a high burst in the past
### Cons
* Can cause high bursts at the window boundaries to leak through
* Causes request stampedes if many users are trying to access your server,
whenever a new window begins
### Usage
```python
from upstash_ratelimit import Ratelimit, FixedWindow
from upstash_redis import Redis
ratelimit = Ratelimit(
redis=Redis.from_env(),
limiter=FixedWindow(max_requests=10, window=10),
)
```
## Sliding Window
Builds on top of fixed window but instead of a fixed window, we use a rolling
window. Take this example: We have a rate limit of 10 requests per 1 minute. We
divide time into 1 minute slices, just like in the fixed window algorithm.
Window 1 will be from 00:00:00 to 00:01:00 (HH:MM:SS). Let's assume it is
currently 00:01:15 and we have received 4 requests in the first window and 5
requests so far in the current window. The approximation to determine if the
request should pass works like this:
```python
limit = 10
# 4 request from the old window, weighted + requests in current window
rate = 4 * ((60 - 15) / 60) + 5 = 8
return rate < limit # True means we should allow the request
```
### Pros
* Solves the issue near boundary from fixed window.
### Cons
* More expensive in terms of storage and computation
* It's only an approximation because it assumes a uniform request flow in the
previous window
### Usage
```python
from upstash_ratelimit import Ratelimit, SlidingWindow
from upstash_redis import Redis
ratelimit = Ratelimit(
redis=Redis.from_env(),
limiter=SlidingWindow(max_requests=10, window=10),
)
```
`reset` field in the [`limit`](/redis/sdks/ratelimit-py/gettingstarted) method of sliding window does not
provide an exact reset time. Instead, the reset time is the start time of
the next window.
## Token Bucket
Consider a bucket filled with maximum number of tokens that refills constantly
at a rate per interval. Every request will remove one token from the bucket and
if there is no token to take, the request is rejected.
### Pros
* Bursts of requests are smoothed out and you can process them at a constant
rate.
* Allows setting a higher initial burst limit by setting maximum number of
tokens higher than the refill rate
### Cons
* Expensive in terms of computation
### Usage
```python
from upstash_ratelimit import Ratelimit, TokenBucket
from upstash_redis import Redis
ratelimit = Ratelimit(
redis=Redis.from_env(),
limiter=TokenBucket(max_tokens=10, refill_rate=5, interval=10),
)
```
# Features
Source: https://upstash.com/docs/redis/sdks/ratelimit-py/features
## Block until ready
You also have the option to try and wait for a request to pass in the given
timeout.
It is very similar to the `limit` method and takes an identifier and returns the
same response. However if the current limit has already been exceeded, it will
automatically wait until the next window starts and will try again. Setting the
timeout parameter (in seconds) will cause the method to block a finite amount of
time.
```python
from upstash_ratelimit import Ratelimit, SlidingWindow
from upstash_redis import Redis
# Create a new ratelimiter, that allows 10 requests per 10 seconds
ratelimit = Ratelimit(
redis=Redis.from_env(),
limiter=SlidingWindow(max_requests=10, window=10),
)
response = ratelimit.block_until_ready("id", timeout=30)
if not response.allowed:
print("Unable to process, even after 30 seconds")
else:
do_expensive_calculation()
print("Here you go!")
```
## Using multiple limits
Sometimes you might want to apply different limits to different users. For
example you might want to allow 10 requests per 10 seconds for free users, but
60 requests per 10 seconds for paid users.
Here's how you could do that:
```python
from upstash_ratelimit import Ratelimit, SlidingWindow
from upstash_redis import Redis
class MultiRL:
def __init__(self) -> None:
redis = Redis.from_env()
self.free = Ratelimit(
redis=redis,
limiter=SlidingWindow(max_requests=10, window=10),
prefix="ratelimit:free",
)
self.paid = Ratelimit(
redis=redis,
limiter=SlidingWindow(max_requests=60, window=10),
prefix="ratelimit:paid",
)
# Create a new ratelimiter, that allows 10 requests per 10 seconds
ratelimit = MultiRL()
ratelimit.free.limit("userIP")
ratelimit.paid.limit("userIP")
```
## Custom Rates
When rate limiting, you may want different requests to consume different amounts of tokens.
This could be useful when processing batches of requests where you want to rate limit based
on items in the batch or when you want to rate limit based on the number of tokens.
To achieve this, you can simply pass `rate` parameter when calling the limit method:
```python
from upstash_ratelimit import Ratelimit, FixedWindow
from upstash_redis import Redis
ratelimit = Ratelimit(
redis=Redis.from_env(),
limiter=FixedWindow(max_requests=10, window=10),
)
# pass rate as 5 to subtract 5 from the number of
# allowed requests in the window:
identifier = "api"
response = ratelimit.limit(identifier, rate=5)
```
# Getting Started
Source: https://upstash.com/docs/redis/sdks/ratelimit-py/gettingstarted
## Install
```bash
pip install upstash-ratelimit
```
## Create database
To be able to use upstash-ratelimit, you need to create a database on
[Upstash](https://console.upstash.com/).
## Usage
For possible Redis client configurations, have a look at the
[Redis SDK repository](https://github.com/upstash/redis-python).
> This library supports asyncio as well. To use it, import the asyncio-based
> variant from the `upstash_ratelimit.asyncio` module.
```python
from upstash_ratelimit import Ratelimit, FixedWindow
from upstash_redis import Redis
# Create a new ratelimiter, that allows 10 requests per 10 seconds
ratelimit = Ratelimit(
redis=Redis.from_env(),
limiter=FixedWindow(max_requests=10, window=10),
# Optional prefix for the keys used in Redis. This is useful
# if you want to share a Redis instance with other applications
# and want to avoid key collisions. The default prefix is
# "@upstash/ratelimit"
prefix="@upstash/ratelimit",
)
# Use a constant string to limit all requests with a single ratelimit
# Or use a user ID, API key or IP address for individual limits.
identifier = "api"
response = ratelimit.limit(identifier)
if not response.allowed:
print("Unable to process at this time")
else:
do_expensive_calculation()
print("Here you go!")
```
The `limit` method also returns the following metadata:
```python
@dataclasses.dataclass
class Response:
allowed: bool
"""
Whether the request may pass(`True`) or exceeded the limit(`False`)
"""
limit: int
"""
Maximum number of requests allowed within a window.
"""
remaining: int
"""
How many requests the user has left within the current window.
"""
reset: float
"""
Unix timestamp in seconds when the limits are reset
"""
```
# Overview
Source: https://upstash.com/docs/redis/sdks/ratelimit-py/overview
`upstash-ratelimit` is a connectionless rate limiting library for Python,
designed to be used in serverless environments such as:
* AWS Lambda
* Vercel Serverless
* Google Cloud Functions
* and other environments where HTTP is preferred over TCP.
The SDK is currently compatible with Python 3.8 and above.
You can find the Github Repository [here](https://github.com/upstash/ratelimit-python).
# Ratelimiting Algorithms
Source: https://upstash.com/docs/redis/sdks/ratelimit-ts/algorithms
We provide different algorithms to use out of the box. Each has pros and cons.
## Fixed Window
This algorithm divides time into fixed durations/windows. For example each
window is 10 seconds long. When a new request comes in, the current time is used
to determine the window and a counter is increased. If the counter is larger
than the set limit, the request is rejected.
In fixed & sliding window algorithms, the reset time is based on fixed time boundaries (which depend on the period), not on when the first request was made. So two requests made right before the window ends still count toward the current window, and limits reset at the start of the next window.
### Pros
* Very cheap in terms of data size and computation
* Newer requests are not starved due to a high burst in the past
### Cons
* Can cause high bursts at the window boundaries to leak through
* Causes request stampedes if many users are trying to access your server,
whenever a new window begins
### Usage
Create a new ratelimiter, that allows 10 requests per 10 seconds.
```ts
const ratelimit = new Ratelimit({
redis: Redis.fromEnv(),
limiter: Ratelimit.fixedWindow(10, "10 s"),
});
```
```ts
const ratelimit = new MultiRegionRatelimit({
redis: [
new Redis({
/* auth */
}),
new Redis({
/* auth */
})
],
limiter: MultiRegionRatelimit.fixedWindow(10, "10 s"),
});
```
## Sliding Window
Builds on top of fixed window but instead of a fixed window, we use a rolling
window. Take this example: We have a rate limit of 10 requests per 1 minute. We
divide time into 1 minute slices, just like in the fixed window algorithm.
Window 1 will be from 00:00:00 to 00:01:00 (HH:MM:SS). Let's assume it is
currently 00:01:15 and we have received 4 requests in the first window and 5
requests so far in the current window. The approximation to determine if the
request should pass works like this:
```ts
limit = 10
// 4 request from the old window, weighted + requests in current window
rate = 4 * ((60 - 15) / 60) + 5 = 8
return rate < limit // True means we should allow the request
```
### Pros
* Solves the issue near boundary from fixed window.
### Cons
* More expensive in terms of storage and computation
* Is only an approximation, because it assumes a uniform request flow in the
previous window, but this is fine in most cases
### Usage
Create a new ratelimiter, that allows 10 requests per 10 seconds.
```ts
const ratelimit = new Ratelimit({
redis: Redis.fromEnv(),
limiter: Ratelimit.slidingWindow(10, "10 s"),
});
```
**Warning:** Using sliding window algorithm with the multiregion setup results in large number of
commands in Redis and long request processing times. If you want to keep the number of commands
low, we recommend using the [fixed window algorithm in multi region setup](https://upstash.com/docs/redis/sdks/ratelimit-ts/algorithms#fixed-window).
```ts
const ratelimit = new MultiRegionRatelimit({
redis: [
new Redis({
/* auth */
}),
new Redis({
/* auth */
})
],
limiter: MultiRegionRatelimit.slidingWindow(10, "10 s"),
});
```
`reset` field in the [`limit`](/redis/sdks/ratelimit-ts/methods#limit) and [`getRemaining`](/redis/sdks/ratelimit-ts/methods#getremaining) methods of sliding window do not
provide an exact reset time. Instead, the reset time is the start time of
the next window.
## Token Bucket
Consider a bucket filled with `{maxTokens}` tokens that refills constantly at
`{refillRate}` per `{interval}`. Every request will remove one token from the
bucket and if there is no token to take, the request is rejected.
### Pros
* Bursts of requests are smoothed out and you can process them at a constant
rate.
* Allows to set a higher initial burst limit by setting `maxTokens` higher than
`refillRate`
### Cons
* Expensive in terms of computation
### Usage
Create a new bucket, that refills 5 tokens every 10 seconds and has a maximum
size of 10.
```ts
const ratelimit = new Ratelimit({
redis: Redis.fromEnv(),
limiter: Ratelimit.tokenBucket(5, "10 s", 10),
analytics: true,
});
```
*Not yet supported for `MultiRegionRatelimit`*
# Costs
Source: https://upstash.com/docs/redis/sdks/ratelimit-ts/costs
This page details the cost of the Ratelimit algorithms in terms of the number of Redis commands. Note that these are calculated for Regional Ratelimits. For [Multi Region Ratelimit](https://upstash.com/docs/redis/sdks/ratelimit-ts/features#multi-region), costs will be higher. Additionally, if a Global Upstash Redis is used as the database, number of commands should be calculated as `(1+readRegionCount) * writeCommandCount + readCommandCount` and plus 1 if analytics is enabled.
The Rate Limit SDK minimizes Redis calls to reduce latency overhead and cost. Number of commands executed by the Rate Limit algorithm depends on the chosen algorithm, as well as the state of the algorithm and the caching.
#### Algorithm State
By state of the algorithm, we refer to the entry in our Redis store regarding some identifier `ip1`. You can imagine that there is a state for every identifier. We name these states in the following manner for the purpose of attributing costs to each one:
| State | Success | Explanation |
| ------------ | ------- | ------------------------------------------------------------------------ |
| First | true | First time the Ratelimit was called with identifier `ip1` |
| Intermediate | true | Second or some other time the Ratelimit was called with identifier `ip1` |
| Rate-Limited | false | Requests with identifier `ip1` which are rate limited. |
For instance, first time we call the algorithm with `ip1`, `PEXPIRE` is called so that the key expires after some time. In the following calls, we still use the same script but don't call `PEXPIRE`. In the rate-limited state, we may avoid using Redis altogether if we can make use of the cache.
#### Cache Result
We distinguish the two cases when the identifier `ip1` is found in cache, resulting in a "hit" and the case when the identifier `ip1` is not found in the cache, resulting in a "miss". The cache only exists in the runtime environment and is independent of the Redis database. The state of the cache is especially relevant for serverless contexts, where the cache will usually be empty because of a cold start.
| Result | Explanation |
| ------ | ------------------------------------------------------------------------------------------------------- |
| Hit | Identifier `ip1` is found in the runtime cache |
| Miss | Identifier `ip1` is not found in cache or the value in the cache doesn't block (rate-limit) the request |
An identifier is saved in the cache only when a request is rate limited after a call to the Redis database. The request to Redis returns a timestamp for the time when such a request won't be rate limited anymore. We save this timestamp in the cache and this allows us to reject any request before this timestamp without having to consult the Redis database.
See the [section on caching](https://upstash.com/docs/redis/sdks/ratelimit-ts/features) for more details.
# Costs
### `limit()`
#### Fixed Window
| Cache Result | Algorithm State | Command Count | Commands |
| ------------ | --------------- | ------------- | ------------------- |
| Hit/Miss | First | 3 | EVAL, INCR, PEXPIRE |
| Hit/Miss | Intermediate | 2 | EVAL, INCR |
| Miss | Rate-Limited | 2 | EVAL, INCR |
| Hit | Rate-Limited | 0 | *utilized cache* |
#### Sliding Window
| Cache Result | Algorithm State | Command Count | Commands |
| ------------ | --------------- | ------------- | ----------------------------- |
| Hit/Miss | First | 5 | EVAL, GET, GET, INCR, PEXPIRE |
| Hit/Miss | Intermediate | 4 | EVAL, GET, GET, INCR |
| Miss | Rate-Limited | 3 | EVAL, GET, GET |
| Hit | Rate-Limited | 0 | *utilized cache* |
#### Token Bucket
| Cache Result | Algorithm State | Command Count | Commands |
| ------------ | ------------------ | ------------- | -------------------------- |
| Hit/Miss | First/Intermediate | 4 | EVAL, HMGET, HSET, PEXPIRE |
| Miss | Rate-Limited | 2 | EVAL, HMGET |
| Hit | Rate-Limited | 0 | *utilized cache* |
### `getRemaining()`
This method doesn't use the cache or it doesn't have a state it depends on. Therefore, every call
results in the same number of commands in Redis.
| Algorithm | Command Count | Commands |
| -------------- | ------------- | -------------- |
| Fixed Window | 2 | EVAL, GET |
| Sliding Window | 3 | EVAL, GET, GET |
| Token Bucket | 2 | EVAL, HMGET |
### `resetUsedTokens()`
This method starts with a `SCAN` command and deletes every key that matches with `DEL` commands:
| Algorithm | Command Count | Commands |
| -------------- | ------------- | -------------------- |
| Fixed Window | 3 | EVAL, SCAN, DEL |
| Sliding Window | 4 | EVAL, SCAN, DEL, DEL |
| Token Bucket | 3 | EVAL, SCAN, DEL |
### `blockUntilReady()`
Works the same as `limit()`.
# Deny List
Enabling deny lists introduces a cost of 2 additional command per `limit` call.
Values passed in `identifier`, `ip`, `userAgent` and `country` are checked with a single `SMISMEMBER` command.
The other command is TTL which is for checking the status of the current ip deny list to figure out whether
it is expired, valid or disabled.
If [Auto IP deny list](https://upstash.com/docs/redis/sdks/ratelimit-ts/features#auto-ip-deny-list) is enabled,
the Ratelimit SDK will update the ip deny list everyday, in the first `limit` invocation after 2 AM UTC.
This will consume 9 commands per day.
If a value is found in the deny list at redis, the client saves this value in the cache and denies
any further requests with that value for a minute without calling Redis (except for analytics).
# Analytics
If analytics is enabled, all calls of `limit` will result in 1 more command since `ZINCRBY` will be called to update the analytics.
# Features
Source: https://upstash.com/docs/redis/sdks/ratelimit-ts/features
## Caching
For extreme load or denial of service attacks, it might be too expensive to call
redis for every incoming request, just to find out it should be blocked because
they have exceeded the limit.
You can use an ephemeral in memory cache by passing some variable of type
`Map` as the `ephemeralCache` option:
```ts
const cache = new Map(); // must be outside of your serverless function handler
// ...
const ratelimit = new Ratelimit({
// ...
ephemeralCache: cache,
});
```
By default, `ephemeralCache` will be initialized with `new Map()` if no value is provided
as the `ephemeralCache` parameter. To disable the cache, one must pass `ephemeralCache: false`.
If enabled, the ratelimiter will keep track of the blocked identifiers and their
reset timestamps. When a request is received with some identifier `ip1` before the reset time of
`ip1`, the request will be denied without having to call Redis. [`reason` field of the
limit response will be `cacheBlock`](https://upstash.com/docs/redis/sdks/ratelimit-ts/methods#limit)
In serverless environments this is only possible if you create the cache or ratelimiter
instance outside of your handler function. While the function is still hot, the
ratelimiter can block requests without having to request data from Redis, thus
saving time and money.
See the section on how caching impacts the cost in the
[costs page](https://upstash.com/docs/redis/sdks/ratelimit-ts/costs#cache-result).
## Timeout
You can define an optional timeout in milliseconds, after which the request will
be allowed to pass regardless of what the current limit is. This can be useful
if you don't want network issues to cause your application to reject requests.
```ts
const ratelimit = new Ratelimit({
redis: Redis.fromEnv(),
limiter: Ratelimit.slidingWindow(10, "10 s"),
timeout: 1000, // 1 second
analytics: true,
});
```
Default value of the timeout is 5 seconds if no `timeout` is provided. When response
is success because of a timeout, this is shown in
[the `reason` field of the limit method](https://upstash.com/docs/redis/sdks/ratelimit-ts/methods#limit).
## Analytics & Dashboard
Another feature of the rate limiting algorithm is to collect analytics.
By default, analytics is disabled. To enable analytics, simply set the `analytics` parameter to `true`:
```js
const ratelimit = new Ratelimit({
redis,
analytics: true,
limiter: Ratelimit.slidingWindow(60, "10s"),
});
```
Everytime we call `ratelimit.limit()`, analytics will be sent to the Redis database
([see costs page](https://upstash.com/docs/redis/sdks/ratelimit-ts/costs#analytics))
and information about the hour, identifier and the number of rate limit success and
failures will be collected. This information can be viewed from the Upstash console.
If you are using rate limiting in Cloudflare Workers, Vercel Edge or a similar environment,
you need to make sure that the analytics request is delivered correctly to the Redis.
Otherwise, you may observe lower numbers than the actual number of calls.
To make sure that the request completes, you can use the `pending` field returned by
the `limit` method. See the
[Asynchronous synchronization between databases](https://upstash.com/docs/redis/sdks/ratelimit-ts/features#asynchronous-synchronization-between-databases)
section to see how `pending` can be used.
### Dashboard
If the analytics is enabled, you can find information about how many requests were made
with which identifiers and how many of the requests were blocked from the [Rate Limit
dashboard in Upstash Console](https://console.upstash.com/ratelimit).
To find the dashboard, simply click the three dots and choose the "Rate Limit Analytics" tab:
In the dashboard, you can find information on how many requests were accepted, how many were blocked
and how many were received in total. Additionally, you can see requests over time; top allowed, rate limited
and denied requests.
**Allowed requests** show the identifiers of the requests which succeeded. **Rate limited requests** show the
identifiers of the requests which were blocked because they surpassed the limit. **Denied requests** show the identifier,
user agent, country, or the IP address which caused the request to fail.
If you are using a custom prefix, you need to use the same in the dashboardās top left corner.
## Using Multiple Limits
Sometimes you might want to apply different limits to different users. For
example you might want to allow 10 requests per 10 seconds for free users, but
60 requests per 10 seconds for paid users.
Here's how you could do that:
```ts
import { Redis } from "@upstash/redis";
import { Ratelimit } from "@upstash/ratelimit";
const redis = Redis.fromEnv();
const ratelimit = {
free: new Ratelimit({
redis,
analytics: true,
prefix: "ratelimit:free",
limiter: Ratelimit.slidingWindow(10, "10s"),
}),
paid: new Ratelimit({
redis,
analytics: true,
prefix: "ratelimit:paid",
limiter: Ratelimit.slidingWindow(60, "10s"),
}),
};
await ratelimit.free.limit(ip);
// or for a paid user you might have an email or userId available:
await ratelimit.paid.limit(userId);
```
## Custom Rates
When we call `limit`, it subtracts 1 from the number of calls/tokens available in
the timeframe by default. But there are use cases where we may want to subtract different
numbers depending on the request.
Consider a case where we receive some input from the user either alone or in batches.
If we want to rate limit based on the number of inputs the user can send, we need a way of
specifying what value to subtract.
This is possible thanks to the `rate` parameter. Simply call the `limit` method like the
following:
```ts
const { success } = await ratelimit.limit("identifier", { rate: batchSize });
```
This way, the algorithm will subtract `batchSize` instead of 1.
## Multi Region
Let's assume you have customers in the US and Europe. In this case you can
create 2 separate global redis databases on [Upstash](https://console.upstash.com)
(one with its primary in US and the other in Europe) and your users will enjoy
the latency of whichever db is closest to them.
Using a single Redis instance with replicas in different regions cannot offer
the same performance as `MultiRegionRatelimit` because all write commands have
to go through the primary, increasing latency in other regions.
Using a single redis instance has the downside of providing low latencies only
to the part of your userbase closest to the deployed db. That's why we also
built `MultiRegionRatelimit` which replicates the state across multiple redis
databases as well as offering lower latencies to more of your users.
`MultiRegionRatelimit` does this by checking the current limit in the closest db
and returning immediately. Only afterwards will the state be asynchronously
replicated to the other databases leveraging
[CRDTs](https://en.wikipedia.org/wiki/Conflict-free_replicated_data_type). Due
to the nature of distributed systems, there is no way to guarantee the set
ratelimit is not exceeded by a small margin. This is the tradeoff for reduced
global latency.
### Usage
The API is the same, except for asking for multiple redis instances:
```ts
import { MultiRegionRatelimit } from "@upstash/ratelimit"; // for deno: see above
import { Redis } from "@upstash/redis";
// Create a new ratelimiter, that allows 10 requests per 10 seconds
const ratelimit = new MultiRegionRatelimit({
redis: [
new Redis({
/* auth */
}),
new Redis({
/* auth */
}),
new Redis({
/* auth */
}),
],
limiter: MultiRegionRatelimit.slidingWindow(10, "10 s"),
analytics: true,
});
// Use a constant string to limit all requests with a single ratelimit
// Or use a userID, apiKey or ip address for individual limits.
const identifier = "api";
const { success } = await ratelimit.limit(identifier);
```
### Asynchronous synchronization between databases
The MultiRegion setup will do some synchronization between databases after
returning the current limit. This can lead to problems on Cloudflare Workers and
therefore Vercel Edge functions, because dangling promises must be taken care
of:
```ts
const { pending } = await ratelimit.limit("id");
context.waitUntil(pending);
```
See more information on `context.waitUntil` at
[Cloudflare](https://developers.cloudflare.com/workers/runtime-apis/context/#waituntil)
and [Vercel](https://vercel.com/docs/functions/edge-middleware/middleware-api#waituntil).
You can also utilize [`waitUntil` from Vercel Functions API](https://vercel.com/docs/functions/functions-api-reference#waituntil).
# Getting Started
Source: https://upstash.com/docs/redis/sdks/ratelimit-ts/gettingstarted
## Create your Redis instance
For the rate limit to work, we need to create an Upstash Redis and get its credentials. To create an Upstash Redis, you can follow the [Upstash Redis "Get Started" guide](https://upstash.com/docs/redis/overall/getstarted).
## Add Ratelimit to Your Project
Once we have a Redis instance, next step is adding the rate limit to your project in its most basic form.
### Install Ratelimit
First, we need to install `@upstash/ratelimit`:
```bash
npm install @upstash/ratelimit
```
```ts
import { Ratelimit } from "https://cdn.skypack.dev/@upstash/ratelimit@latest";
```
### Add Ratelimit to Your Endpoint
Next step is to add Ratelimit to your endpoint. In the example below, you can see how to initialize a Ratelimit and use it:
```ts
import { Ratelimit } from "@upstash/ratelimit"; // for deno: see above
import { Redis } from "@upstash/redis";
// Create a new ratelimiter, that allows 10 requests per 10 seconds
const ratelimit = new Ratelimit({
redis: Redis.fromEnv(),
limiter: Ratelimit.slidingWindow(10, "10 s"),
analytics: true,
/**
* Optional prefix for the keys used in redis. This is useful if you want to share a redis
* instance with other applications and want to avoid key collisions. The default prefix is
* "@upstash/ratelimit"
*/
prefix: "@upstash/ratelimit",
});
// Use a constant string to limit all requests with a single ratelimit
// Or use a userID, apiKey or ip address for individual limits.
const identifier = "api";
const { success } = await ratelimit.limit(identifier);
if (!success) {
return "Unable to process at this time";
}
doExpensiveCalculation();
return "Here you go!";
```
For Cloudflare Workers and Fastly Compute\@Edge, you can use the following imports:
```ts
import { Redis } from "@upstash/redis/cloudflare"; // for cloudflare workers and pages
import { Redis } from "@upstash/redis/fastly"; // for fastly compute@edge
```
In this example, we initialize a Ratelimit with an Upstash Redis. The Uptash Redis instance is created from the environment variables and passed to the Ratelimit instance. Then, we check the access rate using the `ratelimit.limit(identifier)` method. If the `success` field is true, we allow the expensive calculation to go through.
For more examples, see the [Examples](https://upstash.com/docs/redis/sdks/ratelimit-ts/overview#examples).
### Set Environment Variables
Final step is to update the environment variables so that the Ratelimit can communicate with the Upstash Redis. `UPSTASH_REDIS_REST_URL` and `UPSTASH_REDIS_REST_TOKEN` environment variables must be set in order for the `Redis.fromEnv()` command to work. You can get the values of these environment variables from the [Upstash Console](https://console.upstash.com/redis) by navigating to the page of the Redis instance you created.
An alternative of using the `Redis.fromEnv()` method is to pass the variables yourself. This can be useful if you save these environment variables with a different name:
```ts
new Redis({
url: "https://****.upstash.io",
token: "********",
});
```
Here is how you can set the environment variables in different cases:
Go to the "Settings" tab in your project. In the menu to the left, click "Environment Variables". Add `UPSTASH_REDIS_REST_URL` and `UPSTASH_REDIS_REST_TOKEN` environment variables and their values.
Run:
```
npx wrangler secret put UPSTASH_REDIS_REST_URL
```
When prompted, enter the value of `UPSTASH_REDIS_REST_URL` when prompted. Do the same for `UPSTASH_REDIS_REST_TOKEN`:
```
npx wrangler secret put UPSTASH_REDIS_REST_TOKEN
```
Go to the `.env.local` file and add the environment variables:
```
UPSTASH_REDIS_REST_URL=****
UPSTASH_REDIS_REST_TOKEN=****
```
## Serverless Environments
When we use ratelimit in a serverless environment like CloudFlare Workers or Vercel Edge,
we need to be careful about making sure that the rate limiting operations complete correctly
before the runtime ends after returning the response.
This is important in two cases where we do some operations in the backgroung asynchronously after `limit` is called:
1. Using MultiRegion: synchronize Redis instances in different regions
2. Enabling analytics: send analytics to Redis
In these cases, we need to wait for these operations to finish before sending the response to the user. Otherwise, the runtime will end and we won't be able to complete our chores.
In order to wait for these operations to finish, use the `pending` promise:
```ts
const { pending } = await ratelimit.limit("id");
context.waitUntil(pending);
```
See more information on `context.waitUntil` at
[Cloudflare](https://developers.cloudflare.com/workers/runtime-apis/context/#waituntil)
and [Vercel](https://vercel.com/docs/functions/edge-middleware/middleware-api#waituntil).
You can also utilize [`waitUntil` from Vercel Functions API](https://vercel.com/docs/functions/functions-api-reference#waituntil).
## Customizing the Ratelimit Algorithm
There are several algorithms we can use for rate limiting. Explore the different rate-limiting algorithms available; how they work, their advantages and disadvantages in the [Algorithms page](https://upstash.com/docs/redis/sdks/ratelimit-ts/algorithms). You can learn about the **cost in terms of the number of commands**, by referring to the [Costs page](https://upstash.com/docs/redis/sdks/ratelimit-ts/costs).
## Methods
In our example, we only used the `limit` method. There are other methods we can use in the Ratelimit. These are:
* `blockUntilReady`: Process a request only when the rate-limiting algorithm allows it.
* `resetUsedTokens`: Reset the rate limiter state for some identifier.
* `getRemaining`: Get the remaining tokens/requests left for some identifier.
To learn more about these methods, refer to the [Methods page](https://upstash.com/docs/redis/sdks/ratelimit-ts/methods).
## Features
To configure the your Ratelimit according to your needs, you can make use of several features:
Handle blocked requests without having to call your Redis Database
If the Redis call of the ratelimit is not resolved in some timeframe, allow
the request by default
Collect information on which identifiers made how many requests and how many
were blocked
Create a deny list to block requests based on user agents, countries, IP
addresses an more
Consume different amounts of tokens in different requests (example: limiting
based on request/response size)
Utilize several Redis databases in different regions to serve users faster
Use different limits for different kinds of requests (example: paid and free
users)
For more information about the features, see the [Features page](https://upstash.com/docs/redis/sdks/ratelimit-ts/features).
# Configure Upstash Ratelimit Strapi Plugin
Source: https://upstash.com/docs/redis/sdks/ratelimit-ts/integrations/strapi/configurations
After setting up the plugin, it's possible to customize the ratelimiter algorithm and rates. You can also define different rate limits and rate limit algorithms for different routes.
## General Configurations
Enable or disable the plugin.
## Database Configurations
The token to authenticate with the Upstash Redis REST API. You can find this
credential on Upstash Console with the name `UPSTASH_REDIS_REST_TOKEN`
The URL for the Upstash Redis REST API. You can find this credential on
Upstash Console with the name `UPSTASH_REDIS_REST_URL`
The prefix for the rate limit keys. The plugin uses this prefix to store the
rate limit data in Redis.
For example, if the prefix is `@strapi`, the key will be
`@strapi:::`.
Enable analytics for the rate limit. When enabled, the plugin extra insights
related to your ratelimits. You can use this data to analyze the rate limit
usage on [Upstash Console](https://console.upstash.com/ratelimit).
## Strategy
The plugin uses a strategy array to define the rate limits per route. Each strategy object has the following properties:
An array of HTTP methods to apply the rate limit.
For example, `["GET", "POST"]`
The path to apply the rate limit. You can use wildcards to match multiple
routes. For example, `*` matches all routes.
Some examples:
* `path: "/api/restaurants/:id"`
* `path: "/api/restaurants"`
The source to identifiy the user. Requests with the same identifier will be
rate limited under the same limit.
Available sources are:
* `ip`: The IP address of the user.
* `header`: The value of a header key. You should pass the source in the `header.` format.
For example, `header.Authorization` will use the value of the `Authorization`
Enable debug mode for the route. When enabled, the plugin logs the remaining
limits and the block status for each request.
The limiter configuration for the route. The limiter object has the following
properties:
The rate limit algorithm to use. For more information related to algorithms, see docs [**here**](https://upstash.com/docs/redis/sdks/ratelimit-ts/algorithms).
* `fixed-window`: The fixed-window algorithm divides time into fixed intervals. Each interval has a set limit of allowed requests. When a new interval starts, the count resets.
* `sliding-window`:
The sliding-window algorithm uses a rolling time frame. It considers requests from the past X time units, continuously moving forward. This provides a smoother distribution of requests over time.
* `token-bucket`: The token-bucket algorithm uses a bucket that fills with tokens at a steady rate. Each request consumes a token. If the bucket is empty, requests are denied. This allows for bursts of traffic while maintaining a long-term rate limit.
The number of tokens allowed in the time window.
The time window for the rate limit. Available units are `"ms" | "s" | "m" | "h" | "d"`
For example, `20s` means 20 seconds.
The rate at which the bucket refills. **This property is only used for the token-bucket algorithm.**
## Examples
```json Apply rate limit for all routes
{
"strapi-plugin-upstash-ratelimit":{
"enabled":true,
"resolve":"./src/plugins/strapi-plugin-upstash-ratelimit",
"config":{
"enabled":true,
"token":"process.env.UPSTASH_REDIS_REST_TOKEN",
"url":"process.env.UPSTASH_REDIS_REST_URL",
"strategy":[
{
"methods":[
"GET",
"POST"
],
"path":"*",
"identifierSource":"header.Authorization",
"limiter":{
"algorithm":"fixed-window",
"tokens":10,
"window":"20s"
}
}
],
"prefix":"@strapi"
}
}
}
```
```json Apply rate limit with IP
{
"strapi-plugin-upstash-ratelimit": {
"enabled": true,
"resolve": "./src/plugins/strapi-plugin-upstash-ratelimit",
"config": {
"enabled": true,
"token": "process.env.UPSTASH_REDIS_REST_TOKEN",
"url": "process.env.UPSTASH_REDIS_REST_URL",
"strategy": [
{
"methods": ["GET", "POST"],
"path": "*",
"identifierSource": "ip",
"limiter": {
"algorithm": "fixed-window",
"tokens": 10,
"window": "20s"
}
}
],
"prefix": "@strapi"
}
}
}
```
```json Routes with different rate limit algorithms
{
"strapi-plugin-upstash-ratelimit": {
"enabled": true,
"resolve": "./src/plugins/strapi-plugin-upstash-ratelimit",
"config": {
"enabled": true,
"token": "process.env.UPSTASH_REDIS_REST_TOKEN",
"url": "process.env.UPSTASH_REDIS_REST_URL",
"strategy": [
{
"methods": ["GET", "POST"],
"path": "/api/restaurants/:id",
"identifierSource": "header.x-author",
"limiter": {
"algorithm": "fixed-window",
"tokens": 10,
"window": "20s"
}
},
{
"methods": ["GET"],
"path": "/api/restaurants",
"identifierSource": "header.x-author",
"limiter": {
"algorithm": "tokenBucket",
"tokens": 10,
"window": "20s",
"refillRate": 1
}
}
],
"prefix": "@strapi"
}
}
}
```
# Upstash Ratelimit Strapi Integration
Source: https://upstash.com/docs/redis/sdks/ratelimit-ts/integrations/strapi/getting-started
Strapi is an open-source, Node.js based, Headless CMS that saves developers a lot of development time, enabling them to build their application backends quickly by decreasing the lines of code necessary.
You can use Upstash's HTTP and Redis based [Ratelimit package](https://github.com/upstash/ratelimit-js) integration with Strapi to protect your APIs from abuse.
## Getting started
### Installation
```bash npm
npm install --save @upstash/strapi-plugin-upstash-ratelimit
```
```bash yarn
yarn add @upstash/strapi-plugin-upstash-ratelimit
```
### Create database
Create a new redis database on [Upstash Console](https://console.upstash.com/). See [related docs](https://upstash.com/docs/redis/overall/getstarted) for further info related to creating a database.
### Set up environment variables
Get the environment variables from [Upstash Console](https://console.upstash.com/), and set it to `.env` file as below:
```shell .env
UPSTASH_REDIS_REST_TOKEN=""
UPSTASH_REDIS_REST_URL=""
```
### Configure the plugin
You can use
```typescript /config/plugins.ts
export default () => ({
"strapi-plugin-upstash-ratelimit": {
enabled: true,
resolve: "./src/plugins/strapi-plugin-upstash-ratelimit",
config: {
enabled: true,
token: process.env.UPSTASH_REDIS_REST_TOKEN,
url: process.env.UPSTASH_REDIS_REST_URL,
strategy: [
{
methods: ["GET", "POST"],
path: "*",
limiter: {
algorithm: "fixed-window",
tokens: 10,
window: "20s",
},
},
],
prefix: "@strapi",
},
},
});
```
```javascript /config/plugins.js
module.exports = () => ({
"strapi-plugin-upstash-ratelimit": {
enabled: true,
resolve: "./src/plugins/strapi-plugin-upstash-ratelimit",
config: {
enabled: true,
token: process.env.UPSTASH_REDIS_REST_TOKEN,
url: process.env.UPSTASH_REDIS_REST_URL,
strategy: [
{
methods: ["GET", "POST"],
path: "*",
limiter: {
algorithm: "fixed-window",
tokens: 10,
window: "20s",
},
},
],
prefix: "@strapi",
},
},
});
```
# Methods
Source: https://upstash.com/docs/redis/sdks/ratelimit-ts/methods
This page contains information on what methods are available in Ratelimit and how they can be used. For information on the
cost of these operations in term of number of Redis commands, refer to the [Costs page](https://upstash.com/docs/redis/sdks/ratelimit-ts/costs).
## `limit`
The `limit` method is the heart of the Ratelimit algorithm.
```ts
ratelimit.limit(
identifier: string,
req?: {
geo?: Geo;
rate?: number,
ip?: string,
userAgent?: string,
country?: string
},
): Promise
```
It receives an identifier to rate limit. Additionally, it can be passed a `req` parameter which can contain either a
`geo` or a `rate` field. `geo` field is passed to the analytics but is not in use currently. The `rate` field determines
the amount of tokens/requests to subtract from the state of the algorithm with regards to the provided identifier.
The `limit` method returns some more metadata that might be useful to you:
````ts
export type RatelimitResponse = {
/**
* Whether the request may pass(true) or exceeded the limit(false)
*/
success: boolean;
/**
* Maximum number of requests allowed within a window.
*/
limit: number;
/**
* How many requests the user has left within the current window.
*/
remaining: number;
/**
* Unix timestamp in milliseconds when the limits are reset.
*/
reset: number;
/**
* For the MultiRegion setup we do some synchronizing in the background, after returning the current limit.
* Or when analytics is enabled, we send the analytics asynchronously after returning the limit.
* In most case you can simply ignore this.
*
* On Vercel Edge or Cloudflare workers, you need to explicitly handle the pending Promise like this:
*
* ```ts
* const { pending } = await ratelimit.limit("id")
* context.waitUntil(pending)
* ```
*
* See `waitUntil` documentation in
* [Cloudflare](https://developers.cloudflare.com/workers/runtime-apis/handlers/fetch/#contextwaituntil)
* and [Vercel](https://vercel.com/docs/functions/edge-middleware/middleware-api#waituntil)
* for more details.
* ```
*/
pending: Promise;
/**
* Reason behind the result in `success` field.
* - Is set to "timeout" when request times out
* - Is set to "cacheBlock" when an identifier is blocked through cache without calling redis because it was
* rate limited previously.
* - Is set to "denyList" when identifier or one of ip/user-agent/country parameters is in deny list. To enable
* deny list, see `enableProtection` parameter. To edit the deny list, see the Upstash Ratelimit Dashboard
* at https://console.upstash.com/ratelimit.
* - Is set to undefined if rate limit check had to use Redis. This happens in cases when `success` field in
* the response is true. It can also happen the first time sucecss is false.
*/
reason?: RatelimitResponseType;
/**
* The value which was in the deny list if reason: "denyList"
*/
deniedValue?: string;
};
````
## `blockUntilReady`
In case you don't want to reject a request immediately but wait until it can be
processed, we also provide
```ts
ratelimit.blockUntilReady(
identifier: string,
timeout: number
): Promise
```
It is very similar to the `limit` method and takes an identifier and returns the
same response. However if the current limit has already been exceeded, it will
automatically wait until the next window starts and will try again. Setting the
timeout parameter (in milliseconds) will cause the returned Promise to resolve
in a finite amount of time.
```ts
// Create a new ratelimiter, that allows 10 requests per 10 seconds
const ratelimit = new Ratelimit({
redis: Redis.fromEnv(),
limiter: Ratelimit.slidingWindow(10, "10 s"),
analytics: true,
});
// `blockUntilReady` returns a promise that resolves as soon as the request is allowed to be processed, or after 30 seconds
const { success } = await ratelimit.blockUntilReady("id", 30_000);
if (!success) {
return "Unable to process, even after 30 seconds";
}
doExpensiveCalculation();
return "Here you go!";
```
In **Cloudflare**, `blockUntilReady` will not work as intended due to
`Date.now()` not behaving the same as in Node environments.
**For more information, check**:
[https://developers.cloudflare.com/workers/runtime-apis/web-standards](https://developers.cloudflare.com/workers/runtime-apis/web-standards)
## `resetUsedTokens`
This method resets the state of the algorithm with respect to some identifier:
```ts
ratelimit.resetUsedTokens(identifier: string): Promise
```
## `getRemaining`
This method returns the remaining tokens/requests available for some identifier:
```ts
ratelimit.getRemaining(identifier: string): Promise<{
remaining: number;
reset: number;
}>
```
`remaining` is the remaining tokens. `reset` is the reset timestamp.
# Overview
Source: https://upstash.com/docs/redis/sdks/ratelimit-ts/overview
# Upstash Rate Limit
[](https://www.npmjs.com/package/ratelimit)
It is the only connectionless (HTTP based) rate limiting library and designed
for:
* Serverless functions (AWS Lambda, Vercel ...)
* Cloudflare Workers
* Vercel Edge
* Fastly Compute\@Edge
* Next.js, Jamstack ...
* Client side web/mobile applications
* WebAssembly
* and other environments where HTTP is preferred over TCP.
## Quick Links:
* [Github Repository](https://github.com/upstash/ratelimit)
* [Getting Started](https://upstash.com/docs/redis/sdks/ratelimit-ts/gettingstarted)
* [Costs](https://upstash.com/docs/redis/sdks/ratelimit-ts/costs)
## Features
Handle blocked requests without having to call your Redis Database
If the Redis call of the ratelimit is not resolved in some timeframe, allow
the request by default
Collect information on which identifiers made how many requests and how many
were blocked
Create a deny list to block requests based on user agents, countries, IP
addresses and more
Consume different amounts of tokens in different requests (example: limiting
based on request/response size)
Utilize several Redis databases in different regions to serve users faster
Use different limits for different kinds of requests (example: paid and free
users)
For more information about the features, see the [Features tab](https://upstash.com/docs/redis/sdks/ratelimit-ts/features).
## Examples
Rate limit an API in a Nextjs project
Rate limit an API with a Middleware in a Nextjs project
Rate limit an Vercel Edge Function
Use Deny Lists to Protect Your Website
Rate limit access to your Cloudflare Pages app
Rate limit access to your Cloudflare Workers
Rate limit access to a Remix App
Rate limit a Nexjs app using Vercel KV
Rate limit your deno app
Limiting requests to a Chatbot endpoint which streams LLM outputs
# Traffic Protection
Source: https://upstash.com/docs/redis/sdks/ratelimit-ts/traffic-protection
### Deny List
Imagine that you want to block requests from certain countries or from some
user agents. In this case, you can make use of deny lists introduced in
ratelimit version 1.2.1.
Deny lists allow you to block based on IP addresses, user agents, countries
and [identifiers](https://upstash.com/docs/redis/sdks/ratelimit-ts/methods#limit).
To enable checking the deny list in your Ratelimit client, simply pass
`enableProtection` as `true`:
```tsx
const ratelimit = new Ratelimit({
redis: Redis.fromEnv(),
limiter: Ratelimit.slidingWindow(10, "10 s"),
enableProtection: true
analytics: true,
});
```
When `limit` is called, the client will check whether any of these values
are in the deny list and block the request if so.
```tsx
const { success, pending, reason, deniedValue } = ratelimit.limit("userId", {
ip: "ip-address",
userAgent: "user-agent",
country: "country",
});
await pending; // await pending if you have analytics enabled
console.log(success, reason, deniedValue);
// prints: false, "denyList", "ip-address"
```
If a request fails because a value was in deny list, `reason` field will
be `"denyList"`. `deniedValue` will contain the value in the deny list.
See [limit method](https://upstash.com/docs/redis/sdks/ratelimit-ts/methods#limit)
for more detailts.
Client also keeps a **cache** of denied values. When a value is found
in the deny list, the client stores this value in the cache. If this value
is encountered in the following requests, it is **denied without calling
Redis at all**. Items are stored in the cache for a minute. This means that if
you add a new value to the deny list, it will immediately take affect but when you
remove a value, it can take up to a minute for clients to start
accepting the value. This can significantly reduce the number of calls to Redis.
Contents of the deny lists are managed from the [Ratelimit Dashboard](https://upstash.com/docs/redis/sdks/ratelimit-ts/features#dashboard).
You can use the dashboard to add items to the deny list or remove them.
If you have analytics enabled, you can also view the number of denied
requests per country/ip address/user agent/identifier on the dashboard.
Note that we look for exact match when checking a value to see if it's in
the deny lists. **Pattern matching is not supported**.
### Auto IP Deny List
The Auto IP Deny List feature enables the automatic blocking of IP addresses
identified as malicious through open-source IP deny lists. This functionality
uses the [ipsum repository on GitHub](https://github.com/stamparm/ipsum),
which aggregates data from over 30 different deny lists.
To enable protection, set the enableProtection parameter to true. Once activated,
your SDK will automatically block IP addresses by leveraging the IP deny lists
when you provide the request IPs in the limit method.
```ts
const ratelimit = new Ratelimit({
redis: Redis.fromEnv(),
limiter: Ratelimit.slidingWindow(10, "10 s"),
enableProtection: true,
});
```
The IP deny list is updated daily at 2 AM UTC. Upon expiration, the
first call to limit after 2 AM UTC will trigger an update, downloading
the latest IPs from GitHub and refreshing the list in your Redis
instance. The update process occurs asynchronously, allowing you to
return the result to the user while the IP list updates in the
background. To ensure the update completes successfully, utilize the
pending field:
```ts
const { success, pending } = await ratelimit.limit(
content,
{ip: "ip-address"}
);
await pending;
```
For more information on effectively using pending, refer to the
["Asynchronous synchronization between databases" section](https://upstash.com/docs/redis/sdks/ratelimit-ts/features#asynchronous-synchronization-between-databases).
Blocked IPs will be listed in the "Denied" section of the Ratelimit
dashboard, providing a clear overview of the addresses that have
been automatically blocked.
If you prefer to disable the Auto IP Deny List feature while still
using the deny lists, you can do so via the [Ratelimit dashboard on
the Upstash Console](https://console.upstash.com/ratelimit).
# Advanced
Source: https://upstash.com/docs/redis/sdks/ts/advanced
## Disable automatic serialization
Your data is (de)serialized as `json` by default. This works for most use cases
but you can disable it if you want:
```ts
const redis = new Redis({
// ...
automaticDeserialization: false,
});
// or
const redis = Redis.fromEnv({
automaticDeserialization: false,
});
```
This probably breaks quite a few types, but it's a first step in that direction.
Please report bugs and broken types
[here](https://github.com/upstash/upstash-redis/issues/49).
## Keep-Alive
`@upstash/redis` optimizes performance by reusing connections wherever possible, reducing latency.
This is achieved by keeping the client in memory instead of reinitializing it with each new function invocation.
As a result, when a hot lambda function receives a new request, it uses the already initialized client, allowing for the reuse of existing connections to Upstash.
This functionality is enabled by default.
# ECHO
Source: https://upstash.com/docs/redis/sdks/ts/commands/auth/echo
Returns a message back to you. Useful for debugging the connection.
## Arguments
A message to send to the server.
## Response
The same message you sent.
```ts Example
const response = await redis.echo("hello world");
console.log(response); // "hello world"
```
# PING
Source: https://upstash.com/docs/redis/sdks/ts/commands/auth/ping
Send a ping to the server and get a response if the server is alive.
## Arguments
No arguments
## Response
`PONG`
```ts Example
const response = await redis.ping();
console.log(response); // "PONG"
```
# BITCOUNT
Source: https://upstash.com/docs/redis/sdks/ts/commands/bitmap/bitcount
Count the number of set bits.
The `BITCOUNT` command in Redis is used to count the number of set bits (bits with a value of 1) in a range of bytes within a key that is stored as a binary string. It is primarily used for bit-level operations on binary data stored in Redis.
## Arguments
The key to get.
Specify the range of bytes within the binary string to count the set bits. If not provided, it counts set bits in the entire string.
Either specify both `start` and `end` or neither.
Specify the range of bytes within the binary string to count the set bits. If not provided, it counts set bits in the entire string.
Either specify both `start` and `end` or neither.
## Response
The number of set bits in the specified range.
```ts Example
const bits = await redis.bitcount(key);
```
```ts With Range
const bits = await redis.bitcount(key, 5, 10);
```
# BITOP
Source: https://upstash.com/docs/redis/sdks/ts/commands/bitmap/bitop
Perform bitwise operations between strings.
The `BITOP` command in Redis is used to perform bitwise operations on multiple keys (or Redis strings) and store the result in a destination key. It is primarily used for performing logical AND, OR, XOR, and NOT operations on binary data stored in Redis.
## Arguments
Specifies the type of bitwise operation to perform, which can be one of the following: `AND`, `OR`, `XOR`, or `NOT`.
The key to store the result of the operation in.
One or more keys to perform the operation on.
## Response
The size of the string stored in the destination key.
```ts Example
await redis.bitop("AND", "destKey", "sourceKey1", "sourceKey2");
```
# BITPOS
Source: https://upstash.com/docs/redis/sdks/ts/commands/bitmap/bitpos
Find the position of the first set or clear bit (bit with a value of 1 or 0) in a Redis string key.
## Arguments
The key to search in.
The key to store the result of the operation in.
The index to start searching at.
The index to stop searching at.
## Response
The index of the first occurrence of the bit in the string.
```ts Example
await redis.bitpos("key", 1);
```
```ts With Range
await redis.bitpos("key", 1, 5, 20);
```
# GETBIT
Source: https://upstash.com/docs/redis/sdks/ts/commands/bitmap/getbit
Retrieve a single bit.
## Arguments
The key of the bitset
Specify the offset at which to get the bit.
## Response
The bit value stored at offset.
```ts Example
const bit = await redis.getbit(key, 4);
```
# SETBIT
Source: https://upstash.com/docs/redis/sdks/ts/commands/bitmap/setbit
Set a single bit in a string.
## Arguments
The key of the bitset
Specify the offset at which to set the bit.
The bit to set
## Response
The original bit value stored at offset.
```ts Example
const originalBit = await redis.setbit(key, 4, 1);
```
# DEL
Source: https://upstash.com/docs/redis/sdks/ts/commands/generic/del
Removes the specified keys. A key is ignored if it does not exist.
## Arguments
One or more keys to remove.
## Response
The number of keys that were removed.
```ts Basic
await redis.del("key1", "key2");
```
```ts Array
// in case you have an array of keys
const keys = ["key1", "key2"];
await redis.del(...keys)
```
# EXISTS
Source: https://upstash.com/docs/redis/sdks/ts/commands/generic/exists
Check if a key exists.
## Arguments
One or more keys to check.
## Response
The number of keys that exist
```ts Example
await redis.set("key1", "value1")
await redis.set("key2", "value2")
const keys = await redis.exists("key1", "key2", "key3");
console.log(keys) // 2
```
# EXPIRE
Source: https://upstash.com/docs/redis/sdks/ts/commands/generic/expire
Sets a timeout on key. The key will automatically be deleted.
## Arguments
The key to set the timeout on.
How many seconds until the key should be deleted.
## Response
`1` if the timeout was set, `0` otherwise
```ts Example
await redis.set("mykey", "Hello");
await redis.expire("mykey", 10);
```
# EXPIREAT
Source: https://upstash.com/docs/redis/sdks/ts/commands/generic/expireat
Sets a timeout on key. The key will automatically be deleted.
## Arguments
The key to set the timeout on.
A unix timestamp in seconds at which point the key will expire.
## Response
`1` if the timeout was set, `0` otherwise
```ts Example
await redis.set("mykey", "Hello");
const tenSecondsFromNow = Math.floor(Date.now() / 1000) + 10;
await redis.expireat("mykey", tenSecondsFromNow);
```
# KEYS
Source: https://upstash.com/docs/redis/sdks/ts/commands/generic/keys
Returns all keys matching pattern.
This command may block the DB for a long time, depending on its size. We advice against using it in production. Use [SCAN](/redis/sdks/ts/commands/generic/scan) instead.
## Arguments
A glob-style pattern. Use `*` to match all keys.
## Response
Array of keys matching the pattern.
```ts Example
const keys = await redis.keys("prefix*");
```
```ts Match All
const keys = await redis.keys("*");
```
# PERSIST
Source: https://upstash.com/docs/redis/sdks/ts/commands/generic/persist
Remove any timeout set on the key.
## Arguments
The key to persist
## Response
`1` if the timeout was removed, `0` if `key` does not exist or does not have an associated timeout.
```ts Example
await redis.persist(key);
```
# PEXPIRE
Source: https://upstash.com/docs/redis/sdks/ts/commands/generic/pexpire
Sets a timeout on key. After the timeout has expired, the key will automatically be deleted.
## Arguments
The key to expire.
The number of milliseconds until the key expires.
## Response
`1` if the timeout was applied, `0` if `key` does not exist.
```ts Example
await redis.pexpire(key, 60_000); // 1 minute
```
# PEXPIREAT
Source: https://upstash.com/docs/redis/sdks/ts/commands/generic/pexpireat
Sets a timeout on key. After the timeout has expired, the key will automatically be deleted.
## Arguments
The key to expire.
The unix timestamp in milliseconds at which the key will expire.
## Response
`1` if the timeout was applied, `0` if `key` does not exist.
```ts Example
const 10MinutesFromNow = Date.now() + 10 * 60 * 1000;
await redis.pexpireat(key, 10MinutesFromNow);
```
# PTTL
Source: https://upstash.com/docs/redis/sdks/ts/commands/generic/pttl
Return the expiration in milliseconds of a key.
## Arguments
The key
## Response
The number of milliseconds until this expires, negative if the key does not exist or does not have an expiration set.
```ts Example
const millis = await redis.pttl(key);
```
# RANDOMKEY
Source: https://upstash.com/docs/redis/sdks/ts/commands/generic/randomkey
Returns a random key from database
## Arguments
No arguments
## Response
A random key from database, or `null` when database is empty.
```ts Example
const key = await redis.randomkey();
```
# RENAME
Source: https://upstash.com/docs/redis/sdks/ts/commands/generic/rename
Rename a key
## Arguments
The original key.
A new name for the key.
## Response
`OK`
```ts Example
await redis.rename("old", "new");
```
# RENAMENX
Source: https://upstash.com/docs/redis/sdks/ts/commands/generic/renamenx
Rename a key if it does not already exist.
## Arguments
The original key.
A new name for the key.
## Response
`1` if key was renamed, `0` if key was not renamed.
```ts Example
const renamed = await redis.renamenx("old", "new");
```
# SCAN
Source: https://upstash.com/docs/redis/sdks/ts/commands/generic/scan
Scan the database for keys.
## Arguments
The cursor value. Start with "0" on the first call, then use the cursor
returned by each call for the next. It's a string to safely support large
numbers that might exceed JavaScript's number limits.
Glob-style pattern to filter by field names.
Number of fields to return per call.
Filter by type. For example `string`, `hash`, `set`, `zset`, `list`,
`stream`.
## Response
Returns the next cursor and the list of matching keys. When the returned
cursor is "0", the scan is complete.
```ts Basic
const [cursor, keys] = await redis.scan(0, { match: "*" });
```
# TOUCH
Source: https://upstash.com/docs/redis/sdks/ts/commands/generic/touch
Alters the last access time of one or more keys
## Arguments
One or more keys.
## Response
The number of keys that were touched.
```ts Example
await redis.touch("key1", "key2", "key3");
```
# TTL
Source: https://upstash.com/docs/redis/sdks/ts/commands/generic/ttl
Return the expiration in seconds of a key.
## Arguments
The key
## Response
The number of seconds until this expires, negative if the key does not exist or does not have an expiration set.
```ts Example
const seconds = await redis.ttl(key);
```
# TYPE
Source: https://upstash.com/docs/redis/sdks/ts/commands/generic/type
Get the type of a key.
## Arguments
The key to get.
## Response
The type of the key.
One of `string` | `list` | `set` | `zset` | `hash` | `none`
```ts Example
await redis.set("key", "value");
const t = await redis.type("key");
console.log(t) // "string"
```
# UNLINK
Source: https://upstash.com/docs/redis/sdks/ts/commands/generic/unlink
Removes the specified keys. A key is ignored if it does not exist.
## Arguments
One or more keys to unlink.
## Response
The number of keys that were unlinked.
```ts Basic
await redis.unlink("key1", "key2");
```
```ts Array
// in case you have an array of keys
const keys = ["key1", "key2"];
await redis.unlink(...keys)
```
# HDEL
Source: https://upstash.com/docs/redis/sdks/ts/commands/hash/hdel
Deletes one or more hash fields.
## Arguments
The key to get.
One or more fields to delete.
## Response
The number of fields that were removed from the hash.
```ts Example
await redis.hdel(key, 'field1', 'field2');
// returns 5
```
# HEXISTS
Source: https://upstash.com/docs/redis/sdks/ts/commands/hash/hexists
Checks if a field exists in a hash.
## Arguments
The key to get.
The field to check.
## Response
`1` if the hash contains `field`. `0` if the hash does not contain `field`, or `key` does not exist.
```ts Example
await redis.hset("key", "field", "value");
const exists = await redis.hexists("key", "field");
console.log(exists); // 1
```
# HEXPIRE
Source: https://upstash.com/docs/redis/sdks/ts/commands/hash/hexpire
Sets an expiration time for one or more fields in a hash.
## Arguments
The key of the hash.
The field or fields to set an expiration time for.
The time-to-live (TTL) in seconds.
Optional condition for setting the expiration:
* `NX`: Set the expiration only if the field does not already have an expiration.
* `XX`: Set the expiration only if the field already has an expiration.
* `GT`: Set the expiration only if the new TTL is greater than the current TTL.
* `LT`: Set the expiration only if the new TTL is less than the current TTL.
## Response
A list of integers indicating whether the expiry was successfully set.
* `-2` if the field does not exist in the hash or if key doesn't exist.
* `0` if the expiration was not set due to the condition.
* `1` if the expiration was successfully set.
* `2` if called with 0 seconds/milliseconds or a past Unix time.
For more details, see [HEXPIRE documentation](https://redis.io/commands/hexpire).
```ts Example
await redis.hset("my-key", "my-field", "my-value");
const expirationSet = await redis.hexpire("my-key", "my-field", 1);
console.log(expirationSet); // 1
```
# HEXPIREAT
Source: https://upstash.com/docs/redis/sdks/ts/commands/hash/hexpireat
Sets an expiration time for field(s) in a hash in seconds since the Unix epoch.
## Arguments
The key of the hash.
The field(s) to set an expiration time for.
The expiration time as a Unix timestamp in seconds.
Optional condition for setting the expiration:
* `NX`: Set the expiration only if the field does not already have an expiration.
* `XX`: Set the expiration only if the field already has an expiration.
* `GT`: Set the expiration only if the new TTL is greater than the current TTL.
* `LT`: Set the expiration only if the new TTL is less than the current TTL.
## Response
A list of integers indicating whether the expiry was successfully set.
* `-2` if the field does not exist in the hash or if key doesn't exist.
* `0` if the expiration was not set due to the condition.
* `1` if the expiration was successfully set.
* `2` if called with 0 seconds/milliseconds or a past Unix time.
For more details, see [HEXPIREAT documentation](https://redis.io/commands/hexpireat).
```ts Example
await redis.hset("my-key", "my-field", "my-value");
const expirationSet = await redis.hexpireat("my-key", "my-field", Math.floor(Date.now() / 1000) + 10);
console.log(expirationSet); // [1]
```
# HEXPIRETIME
Source: https://upstash.com/docs/redis/sdks/ts/commands/hash/hexpiretime
Retrieves the expiration time of field(s) in a hash in seconds.
## Arguments
The key of the hash.
The field(s) to retrieve the expiration time for.
## Response
The expiration time in seconds since the Unix epoch for each field.
* `-2` if the field does not exist in the hash or if the key doesn't exist.
* `-1` if the field exists but has no associated expiration.
For more details, see [HEXPIRETIME documentation](https://redis.io/commands/hexpiretime).
```ts Example
await redis.hset("my-key", "my-field", "my-value");
await redis.hexpireat("my-key", "my-field", Math.floor(Date.now() / 1000) + 10);
const expireTime = await redis.hexpiretime("my-key", "my-field");
console.log(expireTime); // e.g., [1697059200]
```
# HGET
Source: https://upstash.com/docs/redis/sdks/ts/commands/hash/hget
Retrieves the value of a hash field.
## Arguments
The key to get.
The field to get.
## Response
The value of the field, or `null`, when field is not present in the hash or key does not exist.
```ts Example
await redis.hset("key", {field: "value"});
const field = await redis.hget("key", "field");
console.log(field); // "value"
```
# HGETALL
Source: https://upstash.com/docs/redis/sdks/ts/commands/hash/hgetall
Retrieves all fields from a hash.
## Arguments
The key to get.
## Response
An object with all fields in the hash.
```ts Example
await redis.hset("key", {
field1: "value1",
field2: "value2",
});
const hash = await redis.hgetall("key");
console.log(hash); // { field1: "value1", field2: "value2" }
```
# HINCRBY
Source: https://upstash.com/docs/redis/sdks/ts/commands/hash/hincrby
Increments the value of a hash field by a given amount
## Arguments
The key of the hash.
The field to increment
How much to increment the field by. Can be negative to subtract.
## Response
The new value of the field after the increment.
```ts Example
await redis.hset("key", {
field: 20,
});
const after = await redis.hincrby("key", "field", 2);
console.log(after); // 22
```
# HINCRBYFLOAT
Source: https://upstash.com/docs/redis/sdks/ts/commands/hash/hincrbyfloat
Increments the value of a hash field by a given float value.
## Arguments
The key of the hash.
The field to increment
How much to increment the field by. Can be negative to subtract.
## Response
The new value of the field after the increment.
```ts Example
await redis.hset("key", {
field: 20,
});
const after = await redis.hincrby("key", "field", 2.5);
console.log(after); // 22.5
```
# HKEYS
Source: https://upstash.com/docs/redis/sdks/ts/commands/hash/hkeys
Return all field names in the hash stored at key.
## Arguments
The key of the hash.
## Response
The field names of the hash
```ts Example
await redis.hset("key", {
id: 1,
username: "chronark",
});
const fields = await redis.hkeys("key");
console.log(fields); // ["id", "username"]
```
# HLEN
Source: https://upstash.com/docs/redis/sdks/ts/commands/hash/hlen
Returns the number of fields contained in the hash stored at key.
## Arguments
The key of the hash.
## Response
How many fields are in the hash.
```ts Example
await redis.hset("key", {
id: 1,
username: "chronark",
});
const fields = await redis.hlen("key");
console.log(fields); // 2
```
# HMGET
Source: https://upstash.com/docs/redis/sdks/ts/commands/hash/hmget
Return the requested fields and their values.
## Arguments
The key of the hash.
One or more fields to get.
## Response
An object containing the fields and their values.
```ts Example
await redis.hset("key", {
id: 1,
username: "chronark",
name: "andreas"
});
const fields = await redis.hmget("key", "username", "name");
console.log(fields); // { username: "chronark", name: "andreas" }
```
# HPERSIST
Source: https://upstash.com/docs/redis/sdks/ts/commands/hash/hpersist
Remove the expiration from one or more fields in a hash.
## Arguments
The key of the hash.
The field or fields to remove the expiration from.
## Response
A list of integers indicating the result for each field:
* `-2` if the field does not exist in the hash or if the key doesn't exist.
* `-1` if the field exists but has no associated expiration set.
* `1` if the expiration was successfully removed.
For more details, see [HPERSIST documentation](https://redis.io/commands/hpersist).
```ts Example
await redis.hset("my-key", "my-field", "my-value");
await redis.hpexpire("my-key", "my-field", 1000);
const expirationRemoved = await redis.hpersist("my-key", "my-field");
console.log(expirationRemoved); // [1]
```
# HPEXPIRE
Source: https://upstash.com/docs/redis/sdks/ts/commands/hash/hpexpire
Sets an expiration time for a field in a hash in milliseconds.
## Arguments
The key of the hash.
The field or list of fields within the hash to set the expiry for.
The time-to-live (TTL) in milliseconds.
Optional condition for setting the expiration:
* `NX`: Set the expiration only if the field does not already have an expiration.
* `XX`: Set the expiration only if the field already has an expiration.
* `GT`: Set the expiration only if the new TTL is greater than the current TTL.
* `LT`: Set the expiration only if the new TTL is less than the current TTL.
For more details, see [HPEXPIRE documentation](https://redis.io/commands/hpexpire).
## Response
A list of integers indicating whether the expiry was successfully set.
* `-2` if the field does not exist in the hash or if key doesn't exist.
* `0` if the expiration was not set due to the condition.
* `1` if the expiration was successfully set.
* `2` if called with 0 seconds/milliseconds or a past Unix time.
For more details, see [HPEXPIRE documentation](https://redis.io/commands/hpexpire).
```ts Example
await redis.hset("my-key", "my-field", "my-value");
const expirationSet = await redis.hpexpire("my-key", "my-field", 1000);
console.log(expirationSet); // [1]
```
# HPEXPIREAT
Source: https://upstash.com/docs/redis/sdks/ts/commands/hash/hpexpireat
Sets an expiration time for field(s) in a hash in milliseconds since the Unix epoch.
## Arguments
The key of the hash.
The field(s) to set an expiration time for.
The expiration time as a Unix timestamp in milliseconds.
Optional condition for setting the expiration:
* `NX`: Set the expiration only if the field does not already have an expiration.
* `XX`: Set the expiration only if the field already has an expiration.
* `GT`: Set the expiration only if the new TTL is greater than the current TTL.
* `LT`: Set the expiration only if the new TTL is less than the current TTL.
## Response
A list of integers indicating whether the expiry was successfully set.
* `-2` if the field does not exist in the hash or if key doesn't exist.
* `0` if the expiration was not set due to the condition.
* `1` if the expiration was successfully set.
* `2` if called with 0 seconds/milliseconds or a past Unix time.
For more details, see [HPEXPIREAT documentation](https://redis.io/commands/hpexpireat).
```ts Example
await redis.hset("my-key", "my-field", "my-value");
const expirationSet = await redis.hpexpireat("my-key", "my-field", Date.now() + 1000);
console.log(expirationSet); // [1]
```
# HPEXPIRETIME
Source: https://upstash.com/docs/redis/sdks/ts/commands/hash/hpexpiretime
Retrieves the expiration time of a field in a hash in milliseconds.
## Arguments
The key of the hash.
The field(s) to retrieve the expiration time for.
## Response
The expiration time in milliseconds since the Unix epoch.
* `-2` if the field does not exist in the hash or if the key doesn't exist.
* `-1` if the field exists but has no associated expiration.
For more details, see [HPEXPIRETIME documentation](https://redis.io/commands/hpexpiretime).
```ts Example
await redis.hset("my-key", "my-field", "my-value");
await redis.hpexpireat("my-key", "my-field", Date.now() + 1000);
const expireTime = await redis.hpexpiretime("my-key", "my-field");
console.log(expireTime); // e.g., 1697059200000
```
# HPTTL
Source: https://upstash.com/docs/redis/sdks/ts/commands/hash/hpttl
Retrieves the remaining time-to-live (TTL) for field(s) in a hash in milliseconds.
## Arguments
The key of the hash.
The field(s) to retrieve the TTL for.
## Response
The remaining TTL in milliseconds for each field.
* `-2` if the field does not exist in the hash or if the key doesn't exist.
* `-1` if the field exists but has no associated expiration.
For more details, see [HPTTL documentation](https://redis.io/commands/hpttl).
```ts Example
await redis.hset("my-key", "my-field", "my-value");
await redis.hpexpire("my-key", "my-field", 1000);
const ttl = await redis.hpttl("my-key", "my-field");
console.log(ttl); // e.g., [950]
```
# HRANDFIELD
Source: https://upstash.com/docs/redis/sdks/ts/commands/hash/hrandfield
Return a random field from a hash
## Arguments
The key of the hash.
Optionally return more than one field.
Return the values of the fields as well.
## Response
An object containing the fields and their values.
```ts Basic
await redis.hset("key", {
id: 1,
username: "chronark",
name: "andreas"
});
const randomField = await redis.hrandfield("key");
console.log(randomField); // one of "id", "username" or "name"
```
```ts Multiple Fields
await redis.hset("key", {
id: 1,
username: "chronark",
name: "andreas",
});
const randomFields = await redis.hrandfield("key", 2);
console.log(randomFields); // ["id", "username"] or any other combination
```
```ts With Values
await redis.hset("key", {
id: 1,
username: "chronark",
name: "andreas",
});
const randomFields = await redis.hrandfield("key", 2, true);
console.log(randomFields); // { id: "1", username: "chronark" } or any other combination
```
# HSCAN
Source: https://upstash.com/docs/redis/sdks/ts/commands/hash/hscan
Scan a hash for fields.
## Arguments
The key of the hash.
The cursor, use `0` in the beginning and then use the returned cursor for subsequent calls.
Glob-style pattern to filter by field names.
Number of fields to return per call.
## Response
The new cursor and the fields array in format `[field, value, field, value]`.
If the new cursor is `0` the iteration is complete.
```ts Basic
await redis.hset("key", {
id: 1,
username: "chronark",
name: "andreas"
});
const [newCursor, fields] = await redis.hscan("key", 0);
console.log(newCursor); // likely `0` since this is a very small hash
console.log(fields); // ["id", 1, "username", "chronark", "name", "andreas"]
```
```ts Match
await redis.hset("key", {
id: 1,
username: "chronark",
name: "andreas",
});
const [newCursor, fields] = await redis.hscan("key", 0, { match: "user*" });
console.log(newCursor); // likely `0` since this is a very small hash
console.log(fields); // ["username", "chronark"]
```
```ts Count
await redis.hset("key", {
id: 1,
username: "chronark",
name: "andreas",
});
const [newCursor, fields] = await redis.hscan("key", 0, { count: 2 });
console.log(fields); // ["id", 1, "name", "andreas", "username", "chronark"]
```
# HSET
Source: https://upstash.com/docs/redis/sdks/ts/commands/hash/hset
Write one or more fields to a hash.
## Arguments
The key of the hash.
An object of fields and their values.
## Response
The number of fields that were added.
```ts Example
await redis.hset("key", {
id: 1,
username: "chronark",
name: "andreas"
});
```
# HSETNX
Source: https://upstash.com/docs/redis/sdks/ts/commands/hash/hsetnx
Write a field to a hash but only if the field does not exist.
## Arguments
The key of the hash.
The name of the field.
Any value, if it's not a string it will be serialized to JSON.
## Response
`1` if the field was set, `0` if it already existed.
```ts Example
await redis.hsetnx("key", "id", 1)
```
# HSTRLEN
Source: https://upstash.com/docs/redis/sdks/ts/commands/hash/hstrlen
Returns the string length of a value in a hash.
## Arguments
The key of the hash.
The name of the field.
## Response
`0` if the hash or field does not exist. Otherwise the length of the string.
```ts Example
const length = await redis.hstrlen("key", "field")
```
# HTTL
Source: https://upstash.com/docs/redis/sdks/ts/commands/hash/httl
Retrieves the remaining time-to-live (TTL) for field(s) in a hash in seconds.
## Arguments
The key of the hash.
The field(s) to retrieve the TTL for.
## Response
The remaining TTL in seconds for each field.
* `-2` if the field does not exist in the hash or if the key doesn't exist.
* `-1` if the field exists but has no associated expiration.
For more details, see [HTTL documentation](https://redis.io/commands/httl).
```ts Example
await redis.hset("my-key", "my-field", "my-value");
await redis.hexpire("my-key", "my-field", 10);
const ttl = await redis.httl("my-key", "my-field");
console.log(ttl); // e.g., [9]
```
# HVALS
Source: https://upstash.com/docs/redis/sdks/ts/commands/hash/hvals
Returns all values in the hash stored at key.
## Arguments
The key of the hash.
## Response
All values in the hash, or an empty list when key does not exist.
```ts Example
await redis.hset("key", {
field1: "Hello",
field2: "World",
})
const values = await redis.hvals("key")
console.log(values) // ["Hello", "World"]
```
# JSON.ARRAPPEND
Source: https://upstash.com/docs/redis/sdks/ts/commands/json/arrappend
Append values to the array at path in the JSON document at key.
To specify a string as an array value to append, wrap the quoted string with an additional set of single quotes. Example: '"silver"'.
## Arguments
The key of the json entry.
The path of the array.
One or more values to append to the array.
## Response
The length of the array after the appending.
```ts Example
await redis.json.arrappend("key", "$.path.to.array", "a");
```
# JSON.ARRINDEX
Source: https://upstash.com/docs/redis/sdks/ts/commands/json/arrindex
Search for the first occurrence of a JSON value in an array.
## Arguments
The key of the json entry.
The path of the array.
The value to search for.
The start index.
The stop index.
## Response
The index of the first occurrence of the value in the array, or -1 if not found.
```ts Example
const index = await redis.json.arrindex("key", "$.path.to.array", "a");
```
# JSON.ARRINSERT
Source: https://upstash.com/docs/redis/sdks/ts/commands/json/arrinsert
Insert the json values into the array at path before the index (shifts to the right).
## Arguments
The key of the json entry.
The path of the array.
The index where to insert the values.
One or more values to append to the array.
## Response
The length of the array after the insertion.
```ts Example
const length = await redis.json.arrinsert("key", "$.path.to.array", 2, "a", "b");
```
# JSON.ARRLEN
Source: https://upstash.com/docs/redis/sdks/ts/commands/json/arrlen
Report the length of the JSON array at `path` in `key`.
## Arguments
The key of the json entry.
The path of the array.
## Response
The length of the array.
```ts Example
const length = await redis.json.arrlen("key", "$.path.to.array");
```
# JSON.ARRPOP
Source: https://upstash.com/docs/redis/sdks/ts/commands/json/arrpop
Remove and return an element from the index in the array. By default the last element from an array is popped.
## Arguments
The key of the json entry.
The path of the array.
The index of the element to pop.
## Response
The popped element or null if the array is empty.
```ts Example
const element = await redis.json.arrpop("key", "$.path.to.array");
```
```ts First
const firstElement = await redis.json.arrpop("key", "$.path.to.array", 0);
```
# JSON.ARRTRIM
Source: https://upstash.com/docs/redis/sdks/ts/commands/json/arrtrim
Trim an array so that it contains only the specified inclusive range of elements.
## Arguments
The key of the json entry.
The path of the array.
The start index of the range.
The stop index of the range.
## Response
The length of the array after the trimming.
```ts Example
const length = await redis.json.arrtrim("key", "$.path.to.array", 2, 10);
```
# JSON.CLEAR
Source: https://upstash.com/docs/redis/sdks/ts/commands/json/clear
Clear container values (arrays/objects) and set numeric values to 0.
## Arguments
The key of the json entry.
The path to clear
## Response
How many values were cleared.
```ts Example
await redis.json.clear("key");
```
```ts With path
await redis.json.clear("key", "$.my.key");
```
# JSON.DEL
Source: https://upstash.com/docs/redis/sdks/ts/commands/json/del
Delete a key from a JSON document.
## Arguments
The key of the json entry.
The path to delete
## Response
How many paths were deleted.
```ts Example
await redis.json.del("key", "$.path.to.value");
```
# JSON.FORGET
Source: https://upstash.com/docs/redis/sdks/ts/commands/json/forget
Delete a key from a JSON document.
## Arguments
The key of the json entry.
The path to forget.
## Response
How many paths were deleted.
```ts Example
await redis.json.forget("key", "$.path.to.value");
```
# JSON.GET
Source: https://upstash.com/docs/redis/sdks/ts/commands/json/get
Get a single value from a JSON document.
## Arguments
The key of the json entry.
Sets the indentation string for nested levels.
Sets the string that's printed at the end of each line.
Sets the string that is put between a key and a value.
One or more paths to retrieve from the JSON document.
## Response
The value at the specified path or `null` if the path does not exist.
```ts Example
const value = await redis.json.get("key", "$.path.to.somewhere");
```
```ts With Options
const value = await redis.json.get("key", {
indent: " ",
newline: "\n",
space: " ",
}, "$.path.to.somewhere");
```
# JSON.MERGE
Source: https://upstash.com/docs/redis/sdks/ts/commands/json/merge
Merges the JSON value at path in key with the provided value.
## Arguments
The key of the json entry.
The path of the value to set.
The value to merge with.
## Response
Returns "OK" if the merge was successful.
```ts Example
await redis.json.merge("key", "$.path.to.value", {"new": "value"})
```
# JSON.MGET
Source: https://upstash.com/docs/redis/sdks/ts/commands/json/mget
Get the same path from multiple JSON documents.
## Arguments
One or more keys of JSON documents.
The path to get from the JSON document.
## Response
The values at the specified path or `null` if the path does not exist.
```ts Example
const values = await redis.json.mget(["key1", "key2"], "$.path.to.somewhere");
```
# JSON.MSET
Source: https://upstash.com/docs/redis/sdks/ts/commands/json/mset
Sets multiple JSON values at multiple paths in multiple keys.
## Arguments
A list of objects where each tuple contains a key, a path, and a value.
Type of value (`TData`) can be `Array`, `string`, `boolean`, `Record`, or `Array`.
## Response
Returns "OK" if the command was successful.
```py Example
await redis.json.mset([
{ key: key, path: "$.path", value: value},
{ key: key2, path: "$.path2", value: value2}
])
```
# JSON.NUMINCRBY
Source: https://upstash.com/docs/redis/sdks/ts/commands/json/numincrby
Increment the number value stored at `path` by number.
## Arguments
The key of the json entry.
The path of the array.
The number to increment by.
## Response
The new value after incrementing
```ts Example
const newValue = await redis.json.numincrby("key", "$.path.to.value", 2);
```
# JSON.NUMMULTBY
Source: https://upstash.com/docs/redis/sdks/ts/commands/json/nummultby
Multiply the number value stored at `path` by number.
## Arguments
The key of the json entry.
The path of the array.
The number to multiply by.
## Response
The new value after multiplying
```ts Example
const newValue = await redis.json.nummultby("key", "$.path.to.value", 2);
```
# JSON.OBJKEYS
Source: https://upstash.com/docs/redis/sdks/ts/commands/json/objkeys
Return the keys in the object that`s referenced by path.
## Arguments
The key of the json entry.
The path of the array.
## Response
The keys of the object at the path.
```ts Example
const keys = await redis.json.objkeys("key", "$.path");
```
# JSON.OBJLEN
Source: https://upstash.com/docs/redis/sdks/ts/commands/json/objlen
Report the number of keys in the JSON object at `path` in `key`.
## Arguments
The key of the json entry.
The path of the object.
## Response
The number of keys in the objects.
```ts Example
const lengths = await redis.json.objlen("key", "$.path");
```
# JSON.SET
Source: https://upstash.com/docs/redis/sdks/ts/commands/json/set
Set the JSON value at path in key.
## Arguments
The key of the json entry.
The path of the value to set.
The value to set.
## Response
`OK`
```ts Example
Set the JSON value at path in key.
redis.json.set(key, "$.path", value);
```
```ts NX
const value = ...
redis.json.set(key, "$.path", value, { nx:true });
```
```ts XX
const value = ...
redis.json.set(key, "$.path", value, { xx:true });
```
# JSON.STRAPPEND
Source: https://upstash.com/docs/redis/sdks/ts/commands/json/strappend
Append the json-string values to the string at path.
## Arguments
The key of the json entry.
The path of the value.
The value to append to the existing string.
## Response
The length of the array after the appending.
```ts Example
await redis.json.strappend("key", "$.path.to.str", "abc");
```
# JSON.STRLEN
Source: https://upstash.com/docs/redis/sdks/ts/commands/json/strlen
Report the length of the JSON String at path in key
## Arguments
The key of the json entry.
The path of the array.
## Response
JSON.STRLEN returns by recursive descent an array of integer replies for each path, the array's length, or nil, if the matching JSON value is not a string.
```ts Example
await redis.json.strlen("key", "$.path.to.str", "a");
```
# JSON.TOGGLE
Source: https://upstash.com/docs/redis/sdks/ts/commands/json/toggle
Toggle a boolean value stored at `path`.
## Arguments
The key of the json entry.
The path of the boolean.
## Response
The new value of the boolean.
```ts Example
const bool = await redis.json.toggle("key", "$.path.to.bool");
```
# JSON.TYPE
Source: https://upstash.com/docs/redis/sdks/ts/commands/json/type
Report the type of JSON value at `path`.
## Arguments
The key of the json entry.
The path of the value.
## Response
The type of the value at `path` or `null` if the value does not exist.
```ts Example
const myType = await redis.json.type("key", "$.path.to.value");
```
# LINDEX
Source: https://upstash.com/docs/redis/sdks/ts/commands/list/lindex
Returns the element at index index in the list stored at key.
The index is zero-based, so 0 means the first element, 1 the second element and so on. Negative indices can be used to designate elements starting at the tail of the list.
## Arguments
The key of the list.
The index of the element to return, zero-based.
## Response
The value of the element at index index in the list. If the index is out of range, `null` is returned.
```ts Example
await redis.rpush("key", "a", "b", "c");
const element = await redis.lindex("key", 0);
console.log(element); // "a"
```
# LINSERT
Source: https://upstash.com/docs/redis/sdks/ts/commands/list/linsert
Insert an element before or after another element in a list
## Arguments
The key of the list.
Whether to insert the element before or after pivot.
The element to insert before or after.
The element to insert.
## Response
The list length after insertion, `0` when the list doesn't exist or `-1` when pivot was not found.
```ts Example
await redis.rpush("key", "a", "b", "c");
await redis.linsert("key", "before", "b", "x");
```
# LLEN
Source: https://upstash.com/docs/redis/sdks/ts/commands/list/llen
Returns the length of the list stored at key.
## Arguments
The key of the list.
## Response
The length of the list at key.
```ts Example
await redis.rpush("key", "a", "b", "c");
const length = await redis.llen("key");
console.log(length); // 3
```
# LMOVE
Source: https://upstash.com/docs/redis/sdks/ts/commands/list/lmove
Move an element from one list to another.
## Arguments
The key of the source list.
The key of the destination list.
The side of the source list from which the element was popped.
The side of the destination list to which the element was pushed.
## Response
The element that was moved.
```ts Example
await redis.rpush("source", "a", "b", "c");
const element = await redis.move("source", "destination", "left", "left");
```
# LPOP
Source: https://upstash.com/docs/redis/sdks/ts/commands/list/lpop
Remove and return the first element(s) of a list
## Arguments
The key of the list.
How many elements to pop. If not specified, a single element is popped.
## Response
The popped element(s). If `count` was specified, an array of elements is
returned, otherwise a single element is returned. If the list is empty, `null`
is returned.
```ts Single
await redis.rpush("key", "a", "b", "c");
const element = await redis.lpop("key");
console.log(element); // "a"
```
```ts Multiple
await redis.rpush("key", "a", "b", "c");
const element = await redis.lpop("key", 2);
console.log(element); // ["a", "b"]
```
# LPOS
Source: https://upstash.com/docs/redis/sdks/ts/commands/list/lpos
Returns the index of matching elements inside a list.
## Arguments
The key of the list.
The element to match.
The rank of the element to match. If specified, the element at the given
rank is matched instead of the first element.
The maximum number of elements to match. If specified, an array of elements
is returned instead of a single element.
Limit the number of comparisons to perform.
## Response
The index of the matching element or an array of indexes if `opts.count` is
specified.
```ts Example
await redis.rpush("key", "a", "b", "c");
const index = await redis.lpos("key", "b");
console.log(index); // 1
```
```ts With Rank
await redis.rpush("key", "a", "b", "c", "b");
const index = await redis.lpos("key", "b", { rank: 2 });
console.log(index); // 3
```
```ts With Count
await redis.rpush("key", "a", "b", "b");
const positions = await redis.lpos("key", "b", { count: 2 });
console.log(positions); // [1, 2]
```
# LPUSH
Source: https://upstash.com/docs/redis/sdks/ts/commands/list/lpush
Push an element at the head of the list.
## Arguments
The key of the list.
One or more elements to push at the head of the list.
## Response
The length of the list after the push operation.
```ts Example
const length1 = await redis.lpush("key", "a", "b", "c");
console.log(length1); // 3
const length2 = await redis.lpush("key", "d");
console.log(length2); // 4
```
# LPUSHX
Source: https://upstash.com/docs/redis/sdks/ts/commands/list/lpushx
Push an element at the head of the list only if the list exists.
## Arguments
The key of the list.
One or more elements to push at the head of the list.
## Response
The length of the list after the push operation.
`0` if the list did not exist and thus no element was pushed.
```ts Example
await redis.lpush("key", "a", "b", "c");
const length = await redis.lpushx("key", "d");
console.log(length); // 4
```
```ts Without existing list
const length = await redis.lpushx("key", "a");
console.log(length); // 0
```
# LRANGE
Source: https://upstash.com/docs/redis/sdks/ts/commands/list/lrange
Returns the specified elements of the list stored at key.
## Arguments
The key of the list.
The starting index of the range to return.
Use negative numbers to specify offsets starting at the end of the list.
The ending index of the range to return.
Use negative numbers to specify offsets starting at the end of the list.
## Response
The list of elements in the specified range.
```ts Example
await redis.lpush("key", "a", "b", "c");
const elements = await redis.lrange("key", 1, 2);
console.log(elements) // ["b", "c"]
```
# LREM
Source: https://upstash.com/docs/redis/sdks/ts/commands/list/lrem
Remove the first `count` occurrences of an element from a list.
## Arguments
The key of the list.
How many occurrences of the element to remove.
The element to remove
## Response
The number of elements removed.
```ts Example
await redis.lpush("key", "a", "a", "b", "b", "c");
const removed = await redis.lrem("key", 4, "b");
console.log(removed) // 2
```
# LSET
Source: https://upstash.com/docs/redis/sdks/ts/commands/list/lset
Set a value at a specific index.
## Arguments
The key of the list.
At which index to set the value.
The value to set.
## Response
`OK`
```ts Example
await redis.lpush("key", "a", "b", "c");
await redis.lset("key", 1, "d");
// list is now ["a", "d", "c"]
```
# LTRIM
Source: https://upstash.com/docs/redis/sdks/ts/commands/list/ltrim
Trim a list to the specified range
## Arguments
The key of the list.
The index of the first element to keep.
The index of the first element to keep.
## Response
`OK`
```ts Example
await redis.lpush("key", "a", "b", "c", "d");
await redis.ltrim("key", 1, 2);
// the list is now ["b", "c"]
```
# RPOP
Source: https://upstash.com/docs/redis/sdks/ts/commands/list/rpop
Remove and return the last element(s) of a list
## Arguments
The key of the list.
How many elements to pop. If not specified, a single element is popped.
## Response
The popped element(s). If `count` was specified, an array of elements is
returned, otherwise a single element is returned. If the list is empty, `null`
is returned.
```ts Single
await redis.rpush("key", "a", "b", "c");
const element = await redis.rpop("key");
console.log(element); // "c"
```
```ts Multiple
await redis.rpush("key", "a", "b", "c");
const element = await redis.rpop("key", 2);
console.log(element); // ["c", "b"]
```
# RPUSH
Source: https://upstash.com/docs/redis/sdks/ts/commands/list/rpush
Push an element at the end of the list.
## Arguments
The key of the list.
One or more elements to push at the end of the list.
## Response
The length of the list after the push operation.
```ts Example
const length1 = await redis.rpush("key", "a", "b", "c");
console.log(length1); // 3
const length2 = await redis.rpush("key", "d");
console.log(length2); // 4
```
# RPUSHX
Source: https://upstash.com/docs/redis/sdks/ts/commands/list/rpushx
Push an element at the end of the list only if the list exists.
## Arguments
The key of the list.
One or more elements to push at the end of the list.
## Response
The length of the list after the push operation.
`0` if the list did not exist and thus no element was pushed.
```ts Example
await redis.lpush("key", "a", "b", "c");
const length = await redis.rpushx("key", "d");
console.log(length); // 4
```
```ts Without existing list
const length = await redis.rpushx("key", "a");
console.log(length); // 0
```
# Overview
Source: https://upstash.com/docs/redis/sdks/ts/commands/overview
Available Commands in @upstash/redis
Echo the given string.
Ping the server.
Count set bits in a string.
Perform bitwise operations between strings.
Find first bit set or clear in a string.
Returns the bit value at offset in the string value stored at key.
Sets or clears the bit at offset in the string value stored at key.
Delete one or multiple keys.
Determine if a key exists.
Set a key's time to live in seconds.
Set the expiration for a key as a UNIX timestamp.
Find all keys matching the given pattern.
Remove the expiration from a key.
Set a key's time to live in milliseconds.
Set the expiration for a key as a UNIX timestamp specified in milliseconds.
Get the time to live for a key in milliseconds.
Return a random key from the keyspace.
Rename a key.
Rename a key, only if the new key does not exist.
{/*
Create a key using the provided serialized value, previously obtained using DUMP.
*/}
Incrementally iterate the keys space.
{/*
Sort the elements in a list, set or sorted set.
*/}
Alters the last access time of a key(s). Returns the number of existing keys specified.
Get the time to live for a key.
Determine the type stored at key.
Delete one or more keys.
Publish messages to many clients
Appends a new entry to a stream.
Return a range of elements in a stream, with IDs matching the specified IDs interval.
Append a value to a string stored at key.
Decrement the integer value of a key by one.
Decrement the integer value of a key by the given number.
Get the value of a key.
Get the value of a key and delete the key.
Get a substring of the string stored at a key.
Set the string value of a key and return its old value.
Increment the integer value of a key by one.
Increment the integer value of a key by the given amount.
Increment the float value of a key by the given amount.
Get the values of all the given keys.
Set multiple keys to multiple values.
Set multiple keys to multiple values, only if none of the keys exist.
Set the string value of a key.
Overwrite part of a string at key starting at the specified offset.
Get the length of the value stored in a key.
Run multiple commands in a transaction.
# PUBLISH
Source: https://upstash.com/docs/redis/sdks/ts/commands/pubsub/publish
Publish a message to a channel
## Arguments
The channel to publish to.
The message to publish.
## Response
The number of clients who received the message.
```ts Example
const listeners = await redis.publish("my-topic", "my-message");
```
# EVAL
Source: https://upstash.com/docs/redis/sdks/ts/commands/scripts/eval
Evaluate a Lua script server side.
## Arguments
The lua script to run.
All of the keys accessed in the script
All of the arguments you passed to the script
## Response
The result of the script.
```ts Example
const script = `
return ARGV[1]
`
const result = await redis.eval(script, [], ["hello"]);
console.log(result) // "hello"
```
# EVAL_RO
Source: https://upstash.com/docs/redis/sdks/ts/commands/scripts/eval_ro
Evaluate a read-only Lua script server side.
## Arguments
The read-only lua script to run.
All of the keys accessed in the script
All of the arguments you passed to the script
## Response
The result of the script.
```ts Example
const script = `
return ARGV[1]
`
const result = await redis.evalRo(script, [], ["hello"]);
console.log(result) // "hello"
```
# EVALSHA
Source: https://upstash.com/docs/redis/sdks/ts/commands/scripts/evalsha
Evaluate a cached Lua script server side.
`EVALSHA` is like `EVAL` but instead of sending the script over the wire every time, you reference the script by its SHA1 hash. This is useful for caching scripts on the server side.
## Arguments
The sha1 hash of the script.
All of the keys accessed in the script
All of the arguments you passed to the script
## Response
The result of the script.
```ts Example
const result = await redis.evalsha("fb67a0c03b48ddbf8b4c9b011e779563bdbc28cb", [], ["hello"]);
console.log(result) // "hello"
```
# EVALSHA_RO
Source: https://upstash.com/docs/redis/sdks/ts/commands/scripts/evalsha_ro
Evaluate a cached read-only Lua script server side.
`EVALSHA_RO` is like `EVAL_RO` but instead of sending the script over the wire every time, you reference the script by its SHA1 hash. This is useful for caching scripts on the server side.
## Arguments
The sha1 hash of the read-only script.
All of the keys accessed in the script
All of the arguments you passed to the script
## Response
The result of the script.
```ts Example
const result = await redis.evalshaRo("fb67a0c03b48ddbf8b4c9b011e779563bdbc28cb", [], ["hello"]);
console.log(result) // "hello"
```
# SCRIPT EXISTS
Source: https://upstash.com/docs/redis/sdks/ts/commands/scripts/script_exists
Check if scripts exist in the script cache.
## Arguments
The sha1 of the scripts to check.
## Response
An array of numbers. `1` if the script exists, otherwise `0`.
```ts Example
await redis.scriptExists("", "")
// Returns 1
// [1, 0]
```
# SCRIPT FLUSH
Source: https://upstash.com/docs/redis/sdks/ts/commands/scripts/script_flush
Removes all scripts from the script cache.
## Arguments
Performs the flush asynchronously.
Performs the flush synchronously.
```ts Example
await redis.scriptFlush();
```
```ts With options
await redis.scriptFlush({
async: true,
});
```
# SCRIPT LOAD
Source: https://upstash.com/docs/redis/sdks/ts/commands/scripts/script_load
Load the specified Lua script into the script cache.
## Arguments
The script to load.
## Response
The sha1 of the script.
```ts Example
const script = `
local value = redis.call('GET', KEYS[1])
return value
`;
const sha1 = await redis.scriptLoad(script);
```
# DBSIZE
Source: https://upstash.com/docs/redis/sdks/ts/commands/server/dbsize
Count the number of keys in the database.
## Arguments
This command has no arguments
## Response
The number of keys in the database
```ts Example
const keys = await redis.dbsize();
console.log(keys) // 20
```
# FLUSHALL
Source: https://upstash.com/docs/redis/sdks/ts/commands/server/flushall
Deletes all keys permanently. Use with caution!
## Arguments
Whether to perform the operation asynchronously.
Defaults to synchronous.
```ts Sync
await redis.flushall();
```
```ts Async
await redis.flushall({async: true})
```
# FLUSHDB
Source: https://upstash.com/docs/redis/sdks/ts/commands/server/flushdb
Deletes all keys permanently. Use with caution!
## Arguments
Whether to perform the operation asynchronously.
Defaults to synchronous.
```ts Sync
await redis.flushdb();
```
```ts Async
await redis.flushdb({async: true})
```
# SADD
Source: https://upstash.com/docs/redis/sdks/ts/commands/set/sadd
Adds one or more members to a set.
## Arguments
The key of the set.
One or more members to add to the set.
## Response
The number of elements that were added to the set, not including all the elements already present in the set.
```ts Example
// 3
await redis.sadd("key", "a", "b", "c");
// 0
await redis.sadd("key", "a", "b");
```
# SCARD
Source: https://upstash.com/docs/redis/sdks/ts/commands/set/scard
Return how many members are in a set
## Arguments
The key of the set.
## Response
How many members are in the set.
```ts Example
await redis.sadd("key", "a", "b", "c");
const cardinality = await redis.scard("key");
console.log(cardinality); // 3
```
# SDIFF
Source: https://upstash.com/docs/redis/sdks/ts/commands/set/sdiff
Return the difference between sets
## Arguments
The keys of the sets to perform the difference operation on.
## Response
The members of the resulting set.
```ts Example
await redis.sadd("set1", "a", "b", "c");
await redis.sadd("set2", "c", "d", "e");
const diff = await redis.sdiff("set1", "set2");
console.log(diff); // ["a", "b"]
```
# SDIFFSTORE
Source: https://upstash.com/docs/redis/sdks/ts/commands/set/sdiffstore
Write the difference between sets to a new set
## Arguments
The key of the set to store the resulting set in.
The keys of the sets to perform the difference operation on.
## Response
The members of the resulting set.
```ts Example
await redis.sadd("set1", "a", "b", "c");
await redis.sadd("set2", "c", "d", "e");
await redis.sdiff("dest", "set1", "set2");
console.log(diff); // ["a", "b"]
```
# SINTER
Source: https://upstash.com/docs/redis/sdks/ts/commands/set/sinter
Return the intersection between sets
## Arguments
The keys of the sets to perform the intersection operation on.
## Response
The members of the resulting set.
```ts Example
await redis.sadd("set1", "a", "b", "c");
await redis.sadd("set2", "c", "d", "e");
const intersection = await redis.sinter("set1", "set2");
console.log(intersection); // ["c"]
```
# SINTERSTORE
Source: https://upstash.com/docs/redis/sdks/ts/commands/set/sinterstore
Return the intersection between sets and store the resulting set in a key
## Arguments
The key of the set to store the resulting set in.
The keys of the sets to perform the intersection operation on.
## Response
The members of the resulting set.
```ts Example
await redis.sadd("set1", "a", "b", "c");
await redis.sadd("set2", "c", "d", "e");
await redis.sinterstore("destination", "set1", "set2");
```
# SISMEMBER
Source: https://upstash.com/docs/redis/sdks/ts/commands/set/sismember
Check if a member exists in a set
## Arguments
The key of the set to check.
The member to check for.
## Response
`1` if the member exists in the set, `0` if not.
```ts Example
await redis.sadd("set", "a", "b", "c");
const isMember = await redis.sismember("set", "a");
console.log(isMember); // 1
```
# SMEMBERS
Source: https://upstash.com/docs/redis/sdks/ts/commands/set/smembers
Return all the members of a set
## Arguments
The key of the set.
## Response
The members of the set.
```ts Example
await redis.sadd("set", "a", "b", "c");
const members = await redis.smembers("set");
console.log(members); // ["a", "b", "c"]
```
# SMISMEMBER
Source: https://upstash.com/docs/redis/sdks/ts/commands/set/smismember
Check if multiple members exist in a set
## Arguments
The key of the set to check.
The members to check
## Response
An array of `0` and `1` values.
`1` if the member exists in the set, `0` if not.
```ts Example
await redis.sadd("set", "a", "b", "c");
const members = await redis.smismember("set", ["a", "b", "d"]);
console.log(members); // [1, 1, 0]
```
# SMOVE
Source: https://upstash.com/docs/redis/sdks/ts/commands/set/smove
Move a member from one set to another
## Arguments
The key of the set to move the member from.
The key of the set to move the member to.
The members to move
## Response
`1` if the member was moved, `0` if not.
```ts Example
await redis.sadd("original", "a", "b", "c");
const moved = await redis.smove("original", "destination", "a");
// moved: 1
// original: ["b", "c"]
// destination: ["a"]
```
# SPOP
Source: https://upstash.com/docs/redis/sdks/ts/commands/set/spop
Removes and returns one or more random members from a set.
## Arguments
The key of the set.
How many members to remove and return.
## Response
The popped member.
If `count` is specified, an array of members is returned.
```ts Example
await redis.sadd("set", "a", "b", "c");
const popped = await redis.spop("set");
console.log(popped); // "a"
```
```ts With Count
await redis.sadd("set", "a", "b", "c");
const popped = await redis.spop("set", 2);
console.log(popped); // ["a", "b"]
```
# SRANDMEMBER
Source: https://upstash.com/docs/redis/sdks/ts/commands/set/srandmember
Returns one or more random members from a set.
## Arguments
The key of the set.
How many members to return.
## Response
The random member.
If `count` is specified, an array of members is returned.
```ts Example
await redis.sadd("set", "a", "b", "c");
const member = await redis.srandmember("set");
console.log(member); // "a"
```
```ts With Count
await redis.sadd("set", "a", "b", "c");
const members = await redis.srandmember("set", 2);
console.log(members); // ["a", "b"]
```
# SREM
Source: https://upstash.com/docs/redis/sdks/ts/commands/set/srem
Remove one or more members from a set
## Arguments
The key of the set to remove the member from.
One or more members to remove from the set.
## Response
How many members were removed
```ts Example
await redis.sadd("set", "a", "b", "c");
const removed = await redis.srem("set", "a", "b", "d");
console.log(removed); // 2
```
# SSCAN
Source: https://upstash.com/docs/redis/sdks/ts/commands/set/sscan
Scan a set
## Arguments
The key of the set.
The cursor, use `0` in the beginning and then use the returned cursor for subsequent calls.
Glob-style pattern to filter by members.
Number of members to return per call.
## Response
The new cursor and the members.
If the new cursor is `0` the iteration is complete.
```ts Example
await redis.sadd("key", "a", "ab","b", "c");
const [newCursor, fields] = await redis.sscan("key", 0, { match: "a*"});
console.log(newCursor); // likely `0` since this is a very small set
console.log(fields); // ["a", "ab"]
```
# SUNION
Source: https://upstash.com/docs/redis/sdks/ts/commands/set/sunion
Return the union between sets
## Arguments
The keys of the sets to perform the union operation on.
## Response
The members of the resulting set.
```ts Example
await redis.sadd("set1", "a", "b", "c");
await redis.sadd("set2", "c", "d", "e");
const union = await redis.sunion("set1", "set2");
console.log(union); // ["a", "b", "c", "d", "e"]
```
# SUNIONSTORE
Source: https://upstash.com/docs/redis/sdks/ts/commands/set/sunionstore
Return the union between sets and store the resulting set in a key
## Arguments
The key of the set to store the resulting set in.
The keys of the sets to perform the union operation on.
## Response
The members of the resulting set.
```ts Example
await redis.sadd("set1", "a", "b", "c");
await redis.sadd("set2", "c", "d", "e");
await redis.sunionstore("destination", "set1", "set2");
```
# XADD
Source: https://upstash.com/docs/redis/sdks/ts/commands/stream/xadd
Appends one or more new entries to a stream.
## Arguments
The key to of the stream.
The stream entry ID. If `*` is passed, a new ID will be generated
automatically.
Key-value data to be appended to the stream.
Prevent creating the stream if it does not exist.
The trim mode.
{" "}
The threshold value for the trim mode.
The comparison operator for the trim mode.
Limit how many entries will be trimmed at most.
## Response
The ID of the newly added entry.
```ts Example
await redis.xadd(key, "*", { name: "John Doe", age: 30 });
```
```ts Trimming
await redis.xadd(key, "*", { name: "John Doe", age: 30 }, {
trim: {
type: "MAXLEN",
threshold: 1000,
comparison: "=",
},
});
```
# XRANGE
Source: https://upstash.com/docs/redis/sdks/ts/commands/stream/xrange
Returns stream entries matching a given range of IDs.
## Arguments
The key to of the stream.
The stream entry ID to start from.
The stream entry ID to end at.
The maximum number of entries to return.
## Response
An object of stream entries, keyed by their stream ID
```ts Example
const entries = redis.xrange(key, "-", "+");
console.log(entries)
// {
// "1548149259438-0": {
// "field1": "value1",
// "field2": "value2"
// },
// "1548149259438-1": {
// "field1": "value3",
// "field2": "value4"
// }
// }
```
# String Commands
Source: https://upstash.com/docs/redis/sdks/ts/commands/string
## MGET
Load multiple keys at once. For billing purposes, this counts as a single command.
If a key is not found, it will be returned as `null`, so you might end up with `null` values in your response array.
```ts
const values = await redis.mget("key1", "key2", "key3");
```
## MSET
Set multiple values at once. For billing purposes, this counts as a single command.
```ts
await redis.mset({
key1: { a: 1 },
key2: "value2",
key3: true,
});
```
## MSETNX
```ts
```
## PSETEX
```ts
```
## SET
```ts
```
## SETEX
```ts
```
## SETNX
```ts
```
## SETRANGE
```ts
```
## STRLEN
```ts
```
## SUBSTR
```ts
```
# APPEND
Source: https://upstash.com/docs/redis/sdks/ts/commands/string/append
Append a value to a string stored at key.
## Arguments
The key to get.
The value to append.
## Response
How many characters were added to the string.
```ts Example
await redis.append(key, "Hello");
// returns 5
```
# DECR
Source: https://upstash.com/docs/redis/sdks/ts/commands/string/decr
Decrement the integer value of a key by one
If a key does not exist, it is initialized as 0 before performing the operation. An error is returned if the key contains a value of the wrong type or contains a string that can not be represented as integer.
## Arguments
The key to decrement.
## Response
The value at the key after the decrementing.
```ts Example
await redis.set("key", 6);
await redis.decr("key");
// returns 5
```
# DECRBY
Source: https://upstash.com/docs/redis/sdks/ts/commands/string/decrby
Decrement the integer value of a key by a given number.
If a key does not exist, it is initialized as 0 before performing the operation. An error is returned if the key contains a value of the wrong type or contains a string that can not be represented as integer.
## Arguments
The key to decrement.
The amount to decrement by.
## Response
The value at the key after the decrementing.
```ts Example
await redis.set("key", 6);
await redis.decrby("key", 4);
// returns 2
```
# GET
Source: https://upstash.com/docs/redis/sdks/ts/commands/string/get
Return the value of the specified key or `null` if the key doesn't exist.
## Arguments
The key to get.
## Response
The response is the value stored at the key or `null` if the key doesn't exist.
```ts Example
type MyType = {
a: number;
b: string;
}
const value = await redis.get("key");
if (!value) {
// key doesn't exist
} else {
// value is of type MyType
}
```
# GETDEL
Source: https://upstash.com/docs/redis/sdks/ts/commands/string/getdel
Return the value of the specified key and delete the key.
## Arguments
The key to get.
## Response
The response is the value stored at the key or `null` if the key doesn't exist.
```ts Example
type MyType = {
a: number;
b: string;
}
await redis.getdel("key");
// returns {a: 1, b: "2"}
```
# GETRANGE
Source: https://upstash.com/docs/redis/sdks/ts/commands/string/getrange
Return a substring of value at the specified key.
## Arguments
The key to get.
The start index of the substring.
The end index of the substring.
## Response
The substring.
```ts Example
const substring = await redis.getrange("key", 2, 4);
```
# GETSET
Source: https://upstash.com/docs/redis/sdks/ts/commands/string/getset
Return the value of the specified key and replace it with a new value.
## Arguments
The key to get.
The new value to store.
## Response
The response is the value stored at the key or `null` if the key doesn't exist.
```ts Example
const oldValue = await redis.getset("key", newValue);
```
# INCR
Source: https://upstash.com/docs/redis/sdks/ts/commands/string/incr
Increment the integer value of a key by one
If a key does not exist, it is initialized as 0 before performing the operation. An error is returned if the key contains a value of the wrong type or contains a string that can not be represented as integer.
## Arguments
The key to increment.
## Response
The value at the key after the incrementing.
```ts Example
await redis.set("key", 6);
await redis.incr("key");
// returns 7
```
# INCRBY
Source: https://upstash.com/docs/redis/sdks/ts/commands/string/incrby
Increment the integer value of a key by a given number.
If a key does not exist, it is initialized as 0 before performing the operation. An error is returned if the key contains a value of the wrong type or contains a string that can not be represented as integer.
## Arguments
The key to decrement.
The amount to increment by.
## Response
The value at the key after the incrementing.
```ts Example
await redis.set("key", 6);
await redis.incrby("key", 4);
// returns 10
```
# INCRBYFLOAT
Source: https://upstash.com/docs/redis/sdks/ts/commands/string/incrbyfloat
Increment the float value of a key by a given number.
If a key does not exist, it is initialized as 0 before performing the operation. An error is returned if the key contains a value of the wrong type or contains a string that can not be represented as integer.
## Arguments
The key to decrement.
The amount to increment by.
## Response
The value at the key after the incrementing.
```ts Example
await redis.set("key", 6);
await redis.incrbyfloat("key", 4,5);
// returns 10.5
```
# MGET
Source: https://upstash.com/docs/redis/sdks/ts/commands/string/mget
Load multiple keys from Redis in one go.
For billing purposes, this counts as a single command.
## Arguments
Multiple keys to load from Redis.
## Response
An array of values corresponding to the keys passed in. If a key doesn't exist, the value will be `null`.
```ts Example
type MyType = {
a: number;
b: string;
}
const values = await redis.mget("key1", "key2", "key3");
// values.length -> 3
```
# MSET
Source: https://upstash.com/docs/redis/sdks/ts/commands/string/mset
Set multiple keys in one go.
For billing purposes, this counts as a single command.
## Arguments
An object where the keys are the keys to set, and the values are the values to set.
## Response
"OK"
```ts Example
await redis.mset({
key1: 1,
key2: "hello",
key3: { a: 1, b: "hello" },
});
```
# MSETNX
Source: https://upstash.com/docs/redis/sdks/ts/commands/string/msetnx
Set multiple keys in one go unless they exist already.
For billing purposes, this counts as a single command.
## Arguments
An object where the keys are the keys to set, and the values are the values to set.
## Response
`True` if all keys were set, `False` if at least one key was not set.
```ts Example
redis.msetnx({
"key1": "value1",
"key2": "value2"
})
```
# SET
Source: https://upstash.com/docs/redis/sdks/ts/commands/string/set
Set a key to hold a string value.
## Arguments
The key
The value, if this is not a string, we will use `JSON.stringify` to convert it
to a string.
You can pass a few options to the command.
Instead of returning `"OK"`, this will cause the command to return the old
value stored at key, or `null` when key did not exist.
Adds an expiration (in seconds) to the key.
Adds an expiration (in milliseconds) to the key.
Expires the key after the given timestamp (in seconds).
Expires the key after the given timestamp (in milliseconds).
Keeps the old expiration if the key already exists.
Only set the key if it does not already exist.
Only set the key if it already exists.
## Response
`"OK"`
```ts Basic
await redis.set("my-key", {my: "value"});
```
```ts Expire in 60 seconds
await redis.set("my-key", {my: "value"}, {
ex: 60
});
```
```ts Only update
await redis.set("my-key", {my: "value"}, {
xx: true
});
```
# SETRANGE
Source: https://upstash.com/docs/redis/sdks/ts/commands/string/setrange
Writes the value of key at offset.
The SETRANGE command in Redis is used to modify a portion of the value of a key by replacing a substring within the key's existing value. It allows you to update part of the string value associated with a specific key at a specified offset.
## Arguments
The name of the Redis key for which you want to modify the value.
The zero-based index in the value where you want to start replacing characters.
The new string that you want to insert at the specified offset in the existing value.
## Response
The length of the value after it was modified.
```ts Example
await redis.set("key", "helloworld")
const length = await redis.setrange("key", 5, "redis");
console.log(length); // 10
// The value of "key" is now "helloredis"
```
# STRLEN
Source: https://upstash.com/docs/redis/sdks/ts/commands/string/strlen
Return the length of a string stored at a key.
The \`STRLEN\`\` command in Redis is used to find the length of the string value associated with a key. In Redis, keys can be associated with various data types, and one of these data types is the "string." The STRLEN command specifically operates on keys that are associated with string values.
## Arguments
The name of the Redis key.
## Response
The length of the value.
```ts Example
await redis.set("key", "helloworld")
const length = await redis.strlen("key");
console.log(length); // 10
```
# Transactions
Source: https://upstash.com/docs/redis/sdks/ts/commands/transaction
Transactions
You can use transactions or pipelines with the `multi` or `pipeline` method.
Transactions are executed atomically, while pipelines are not. In pipelines you can execute multiple commands at once, but other commands from other clients can be executed in between.
```ts Pipeline
const p = redis.pipeline();
p.set("foo", "bar");
p.get("foo");
const res = await p.exec();
```
```ts Transaction
const tx = redis.multi();
tx.set("foo", "bar");
tx.get("foo");
const res = await tx.exec();
```
For more information on pipelines and transactions, see
[the Pipeline page](https://docs.upstash.com/redis/sdks/ts/pipelining/pipeline-transaction).
# ZADD
Source: https://upstash.com/docs/redis/sdks/ts/commands/zset/zadd
Add a member to a sorted set, or update its score if it already exists.
## Arguments
The key of the sorted set.
Only update elements that already exist. Never add elements.
Only add new elements. Never update elements.
Return the number of elements added or updated.
When this option is specified ZADD acts like ZINCRBY. Only one score-element pair can be specified in this mode.
## Response
The number of elements added to the sorted sets, not including elements already existing for which the score was updated.
If `ch` was specified, the number of elements that were updated.
If `incr` was specified, the new score of `member`.
```ts Simple
await redis.zadd(
"key",
{ score: 2, member: "member" },
{ score: 3, member: "member2"},
);
```
```ts XX
await redis.zadd(
"key",
{ xx: true },
{ score: 2, member: "member" },
)
```
```ts NX
await redis.zadd(
"key",
{ nx: true },
{ score: 2, member: "member" },
)
```
```ts CH
await redis.zadd(
"key",
{ ch: true },
{ score: 2, member: "member" },
)
```
```ts INCR
await redis.zadd(
"key",
{ cincrh: true },
{ score: 2, member: "member" },
)
```
# ZCARD
Source: https://upstash.com/docs/redis/sdks/ts/commands/zset/zcard
Returns the number of elements in the sorted set stored at key.
## Arguments
The key to get.
## Response
The number of elements in the sorted set.
```ts Example
await redis.zadd("key",
{ score: 1, member: "one"},
{ score: 2, member: "two" },
);
const elements = await redis.zrank("key");
console.log(elements); // 2
```
# ZCOUNT
Source: https://upstash.com/docs/redis/sdks/ts/commands/zset/zcount
Returns the number of elements in the sorted set stored at key filterd by score.
## Arguments
The key to get.
The minimum score to filter by.
Use `-inf` to effectively ignore this filter.
Use `(number` to exclude the value.
The maximum score to filter by.
Use `+inf` to effectively ignore this filter.
Use `(number` to exclude the value.
## Response
The number of elements where score is between min and max.
```ts Example
await redis.zadd("key",
{ score: 1, member: "one"},
{ score: 2, member: "two" },
);
const elements = await redis.zcount("key", "(1", "+inf");
console.log(elements); // 1
```
# ZDIFFSTORE
Source: https://upstash.com/docs/redis/sdks/ts/commands/zset/zdiffstore
Writes the difference between sets to a new key.
## Arguments
The key to write the difference to.
How many keys to compare.
The keys to compare.
## Response
The number of elements in the resulting set.
```ts Example
const values = await redis.zdiffstore("destination", 2, "key1", "key2");
```
# ZINCRBY
Source: https://upstash.com/docs/redis/sdks/ts/commands/zset/zincrby
Increment the score of a member.
## Arguments
The key of the sorted set.
The increment to add to the score.
The member to increment.
## Response
The new score of `member` after the increment operation.
```ts Example
await redis.zadd("key", 1, "member");
const value = await redis.zincrby("key", 2, "member");
console.log(value); // 3
```
# ZINTERSTORE
Source: https://upstash.com/docs/redis/sdks/ts/commands/zset/zinterstore
Writes the intersection between sets to a new key.
## Arguments
The key to write the intersection to.
How many keys to compare.
The keys to compare.
The aggregation method.
The weight to apply to each key.
The weights to apply to each key.
## Response
The number of elements in the resulting set.
```ts Simple
await redis.zadd(
"key1",
{ score: 1, member: "member1" },
)
await redis.zadd(
"key2",
{ score: 1, member: "member1" },
{ score: 2, member: "member2" },
)
const res = await redis.zinterstore("destination", 2, ["key1", "key2"]);
console.log(res) // 1
```
```ts With Weights
await redis.zadd(
"key1",
{ score: 1, member: "member1" },
)
await redis.zadd(
"key2",
{ score: 1, member: "member1" },
{ score: 2, member: "member2" },
)
const res = await redis.zinterstore(
"destination",
2,
["key1", "key2"],
{ weights: [2, 3] },
);
console.log(res) // 1
```
```ts Aggregate
await redis.zadd(
"key1",
{ score: 1, member: "member1" },
)
await redis.zadd(
"key2",
{ score: 1, member: "member1" },
{ score: 2, member: "member2" },
)
const res = await redis.zinterstore(
"destination",
2,
["key1", "key2"],
{ aggregate: "sum" },
);
console.log(res) // 1
```
# ZLEXCOUNT
Source: https://upstash.com/docs/redis/sdks/ts/commands/zset/zlexcount
Returns the number of elements in the sorted set stored at key filtered by lex.
## Arguments
The key to get.
The lower lexicographical bound to filter by.
Use `-` to disable the lower bound.
The upper lexicographical bound to filter by.
Use `+` to disable the upper bound.
## Response
The number of matched.
```ts Example
await redis.zadd("key",
{ score: 1, member: "one"},
{ score: 2, member: "two" },
);
const elements = await redis.zlexcount("key", "two", "+");
console.log(elements); // 1
```
# ZMSCORE
Source: https://upstash.com/docs/redis/sdks/ts/commands/zset/zmscore
Returns the scores of multiple members.
## Arguments
The key to get.
## Response
The members of the sorted set.
```ts Example
await redis.zadd("key",
{ score: 1, member: "m1" },
{ score: 2, member: "m2" },
{ score: 3, member: "m3" },
{ score: 4, member: "m4" },
)
const scores = await redis.zmscore("key", ["m2", "m4"])
console.log(scores) // [2, 4]
```
# ZPOPMAX
Source: https://upstash.com/docs/redis/sdks/ts/commands/zset/zpopmax
Removes and returns up to count members with the highest scores in the sorted set stored at key.
## Arguments
The key of the sorted set
## Response
The number of elements removed. Defaults to 1.
```ts Example
const popped = await redis.zpopmax("key", 4);
```
# ZPOPMIN
Source: https://upstash.com/docs/redis/sdks/ts/commands/zset/zpopmin
Removes and returns up to count members with the lowest scores in the sorted set stored at key.
## Arguments
The key of the sorted set
## Response
The number of elements removed. Defaults to 1.
```ts Example
const popped = await redis.zpopmin("key", 4);
```
# ZRANGE
Source: https://upstash.com/docs/redis/sdks/ts/commands/zset/zrange
Returns the specified range of elements in the sorted set stored at key.
## Arguments
The key to get.
The lower bound of the range.
The upper bound of the range.
Whether to include the scores in the response.
Whether to reverse the order of the response.
Whether to use the score as the sort order.
Whether to use lexicographical ordering.
The offset to start from.
The number of elements to return.
## Response
The values in the specified range.
If `withScores` is true, the response will have interleaved members and scores: `[TMember, number, TMember, number, ...]`
```ts Example
await redis.zadd("key",
{ score: 1, member: "m1" },
{ score: 2, member: "m2" },
)
const res = await redis.zrange("key", 1, 3)
console.log(res) // ["m2"]
```
```ts WithScores
await redis.zadd("key",
{ score: 1, member: "m1" },
{ score: 2, member: "m2" },
)
const res = await redis.zrange("key", 1, 3, { withScores: true })
console.log(res) // ["m2", 2]
```
```ts ByScore
await redis.zadd("key",
{ score: 1, member: "m1" },
{ score: 2, member: "m2" },
{ score: 3, member: "m3" },
)
const res = await redis.zrange("key", 1, 2, { byScore: true })
console.log(res) // ["m1", "m2"]
```
# ZRANK
Source: https://upstash.com/docs/redis/sdks/ts/commands/zset/zrank
Returns the rank of a member
## Arguments
The key to get.
The member to get the rank of.
## Response
The rank of the member.
```ts Example
const rank = await redis.rank("key", "member");
```
# ZREM
Source: https://upstash.com/docs/redis/sdks/ts/commands/zset/zrem
Remove one or more members from a sorted set
## Arguments
The key of the sorted set
One or more members to remove
## Response
The number of members removed from the sorted set.
```ts Single
await redis.zrem("key", "member");
```
```ts Multiple
await redis.zrem("key", "member1", "member2");
```
# ZREMRANGEBYLEX
Source: https://upstash.com/docs/redis/sdks/ts/commands/zset/zremrangebylex
Remove all members in a sorted set between the given lexicographical range.
## Arguments
The key of the sorted set
The minimum lexicographical value to remove.
The maximum lexicographical value to remove.
## Response
The number of elements removed from the sorted set.
```ts Example
await redis.zremrangebylex("key", "alpha", "omega")
```
# ZREMRANGEBYRANK
Source: https://upstash.com/docs/redis/sdks/ts/commands/zset/zremrangebyrank
Remove all members in a sorted set between the given ranks.
## Arguments
The key of the sorted set
The minimum rank to remove.
The maximum rank to remove.
## Response
The number of elements removed from the sorted set.
```ts Example
await redis.zremrangebyrank("key", 4, 20)
```
# ZREMRANGEBYSCORE
Source: https://upstash.com/docs/redis/sdks/ts/commands/zset/zremrangebyscore
Remove all members in a sorted set between the given scores.
## Arguments
The key of the sorted set
The minimum score to remove.
The maximum score to remove.
## Response
The number of elements removed from the sorted set.
```ts Example
await redis.zremrangebyscore("key", 2, 5)
```
# ZREVRANK
Source: https://upstash.com/docs/redis/sdks/ts/commands/zset/zrevrank
Returns the rank of a member in a sorted set, with scores ordered from high to low.
## Arguments
The key to get.
The member to get the reverse rank of.
## Response
The reverse rank of the member.
```ts Example
const rank = await redis.rank("key", "member");
```
# ZSCAN
Source: https://upstash.com/docs/redis/sdks/ts/commands/zset/zscan
Scan a sorted set
## Arguments
The key of the sorted set.
The cursor, use `0` in the beginning and then use the returned cursor for subsequent calls.
Glob-style pattern to filter by members.
Number of members to return per call.
## Response
The new cursor and the members.
If the new cursor is `0` the iteration is complete.
```ts Example
await redis.zadd("key",
{ score: 1, member: "a" },
{ score: 2, member: "ab" },
{ score: 3, member: "b" },
{ score: 4, member: "c" },
{ score: 5, member: "d" },
)
const [newCursor, members] = await redis.sscan("key", 0, { match: "a*"});
console.log(newCursor); // likely `0` since this is a very small set
console.log(members); // ["a", "ab"]
```
```ts withCount
await redis.zadd("key",
{ score: 1, member: "a" },
{ score: 2, member: "ab" },
{ score: 3, member: "b" },
{ score: 4, member: "c" },
{ score: 5, member: "d" },
)
const [newCursor, members] = await redis.sscan("key", 0, { match: "a*", count: 1});
console.log(newCursor); // likely `0` since this is a very small set
console.log(members); // ["a"]
```
# ZSCORE
Source: https://upstash.com/docs/redis/sdks/ts/commands/zset/zscore
Returns the scores of a member.
## Arguments
The key to get.
## Response
A member of the sortedset.
```ts Example
await redis.zadd("key",
{ score: 1, member: "m1" },
{ score: 2, member: "m2" },
{ score: 3, member: "m3" },
{ score: 4, member: "m4" },
)
const score = await redis.zscore("key", "m2")
console.log(score) // 2
```
# ZUNIONSTORE
Source: https://upstash.com/docs/redis/sdks/ts/commands/zset/zunionstore
Writes the union between sets to a new key.
## Arguments
The key to write the union to.
How many keys to compare.
The keys to compare.
The aggregation method.
The weight to apply to each key.
The weights to apply to each key.
## Response
The number of elements in the resulting set.
```ts Simple
await redis.zadd(
"key1",
{ score: 1, member: "member1" },
)
await redis.zadd(
"key2",
{ score: 1, member: "member1" },
{ score: 2, member: "member2" },
)
const res = await redis.zunionstore("destination", 2, ["key1", "key2"]);
console.log(res) // 2
```
```ts With Weights
await redis.zadd(
"key1",
{ score: 1, member: "member1" },
)
await redis.zadd(
"key2",
{ score: 1, member: "member1" },
{ score: 2, member: "member2" },
)
const res = await redis.zunionstore(
"destination",
2,
["key1", "key2"],
{ weights: [2, 3] },
);
console.log(res) // 2
```
```ts Aggregate
await redis.zadd(
"key1",
{ score: 1, member: "member1" },
)
await redis.zadd(
"key2",
{ score: 1, member: "member1" },
{ score: 2, member: "member2" },
)
const res = await redis.zunionstore(
"destination",
2,
["key1", "key2"],
{ aggregate: "sum" },
);
console.log(res) // 2
```
# Deployment
Source: https://upstash.com/docs/redis/sdks/ts/deployment
We support various platforms, such as nodejs, cloudflare and fastly. Platforms
differ slightly when it comes to environment variables and their `fetch` api.
Please use the correct import when deploying to special platforms.
## Node.js / Browser
Examples: Vercel, Netlify, AWS Lambda
If you are running on nodejs you can set `UPSTASH_REDIS_REST_URL` and
`UPSTASH_REDIS_REST_TOKEN` as environment variable and create a redis instance
like this:
```ts
import { Redis } from "@upstash/redis"
const redis = new Redis({
url: ,
token: ,
})
// or load directly from env
const redis = Redis.fromEnv()
```
If you are running on nodejs v17 and earlier, `fetch` will not be natively
supported. Platforms like Vercel, Netlify, Deno, Fastly etc. provide a polyfill
for you. But if you are running on bare node, you need to either specify a
polyfill yourself or change the import path slightly:
```typescript
import { Redis } from "@upstash/redis/with-fetch";
```
* [Code example](https://github.com/upstash/upstash-redis/blob/main/examples/nodejs)
## Cloudflare Workers
Cloudflare handles environment variables differently than Node.js. Please add
`UPSTASH_REDIS_REST_URL` and `UPSTASH_REDIS_REST_TOKEN` using
`wrangler secret put ...` or in the cloudflare dashboard.
Afterwards you can create a redis instance:
```ts
import { Redis } from "@upstash/redis/cloudflare"
const redis = new Redis({
url: ,
token: ,
})
// or load directly from global env
// service worker
const redis = Redis.fromEnv()
// module worker
export default {
async fetch(request: Request, env: Bindings) {
const redis = Redis.fromEnv(env)
// ...
}
}
```
* [Code example](https://github.com/upstash/upstash-redis/tree/main/examples/cloudflare-workers)
* [Code example typescript](https://github.com/upstash/upstash-redis/tree/main/examples/cloudflare-workers-with-typescript)
* [Code example Wrangler 1](https://github.com/upstash/upstash-redis/tree/main/examples/cloudflare-workers-with-wrangler-1)
* [Documentation](https://docs.upstash.com/redis/tutorials/cloudflare_workers_with_redis)
## Fastly
Fastly introduces a concept called
[backend](https://developer.fastly.com/reference/api/services/backend/). You
need to configure a backend in your `fastly.toml`. An example can be found
[here](https://github.com/upstash/upstash-redis/blob/main/examples/fastly/fastly.toml).
Until the fastly api stabilizes we recommend creating an instance manually:
```ts
import { Redis } from "@upstash/redis/fastly"
const redis = new Redis({
url: ,
token: ,
backend: ,
})
```
* [Code example](https://github.com/upstash/upstash-redis/tree/main/examples/fastly)
* [Documentation](https://blog.upstash.com/fastly-compute-edge-with-redis)
## Deno
Examples: [Deno Deploy](https://deno.com/deploy),
[Netlify Edge](https://www.netlify.com/products/edge/)
```ts
import { Redis } from "https://deno.land/x/upstash_redis/mod.ts"
const redis = new Redis({
url: ,
token: ,
})
// or
const redis = Redis.fromEnv();
```
# Developing or Testing
Source: https://upstash.com/docs/redis/sdks/ts/developing
When developing or testing your application, you might not want or can not use
Upstash over the internet. In this case, you can use a community project called
[Serverless Redis HTTP (SRH)](https://github.com/hiett/serverless-redis-http)
created by [Scott Hiett](https://x.com/hiettdigital).
SRH is a Redis proxy and connection pooler that uses HTTP rather than the Redis
binary protocol. The aim of this project is to be entirely compatible with
Upstash, and work with any Upstash supported Redis version.
We are working with Scott together to keep SRH up to date with the latest
Upstash features.
## Use cases for SRH:
* For usage in your CI pipelines, creating Upstash databases is tedious, or you
have lots of parallel runs.
* See [Using in GitHub Actions](#in-github-actions) on how to quickly get SRH
setup for this context.
* For usage inside of Kubernetes, or any network whereby the Redis server is not
exposed to the internet.
* See [Using in Docker Compose](#via-docker-compose) for the various setup
options directly using the Docker Container.
* For local development environments, where you have a local Redis server
running, or require offline access.
* See [Using the Docker Command](#via-docker-command), or
[Using Docker Compose](#via-docker-compose).
## Setting up SRH
### Via Docker command
If you have a locally running Redis server, you can simply start an SRH
container that connects to it. In this example, SRH will be running on port
`8080`.
```bash
docker run \
-it -d -p 8080:80 --name srh \
-e SRH_MODE=env \
-e SRH_TOKEN=your_token_here \
-e SRH_CONNECTION_STRING="redis://your_server_here:6379" \
hiett/serverless-redis-http:latest
```
### Via Docker Compose
If you wish to run in Kubernetes, this should contain all the basics would need
to set that up. However, be sure to read the Configuration Options, because you
can create a setup whereby multiple Redis servers are proxied.
```yml
version: "3"
services:
redis:
image: redis
ports:
- "6379:6379"
serverless-redis-http:
ports:
- "8079:80"
image: hiett/serverless-redis-http:latest
environment:
SRH_MODE: env
SRH_TOKEN: example_token
SRH_CONNECTION_STRING: "redis://redis:6379" # Using `redis` hostname since they're in the same Docker network.
```
### In GitHub Actions
SRH works nicely in GitHub Actions because you can run it as a container in a
job's services. Simply start a Redis server, and then SRH alongside it. You
don't need to worry about a race condition of the Redis instance not being
ready, because SRH doesn't create a Redis connection until the first command
comes in.
```yml
name: Test @upstash/redis compatibility
on:
push:
workflow_dispatch:
env:
SRH_TOKEN: example_token
jobs:
container-job:
runs-on: ubuntu-latest
container: denoland/deno
services:
redis:
image: redis/redis-stack-server:6.2.6-v6 # 6.2 is the Upstash compatible Redis version
srh:
image: hiett/serverless-redis-http:latest
env:
SRH_MODE: env # We are using env mode because we are only connecting to one server.
SRH_TOKEN: ${{ env.SRH_TOKEN }}
SRH_CONNECTION_STRING: redis://redis:6379
steps:
# You can place your normal testing steps here. In this example, we are running SRH against the upstash/upstash-redis test suite.
- name: Checkout code
uses: actions/checkout@v3
with:
repository: upstash/upstash-redis
- name: Run @upstash/redis Test Suite
run: deno test -A ./pkg
env:
UPSTASH_REDIS_REST_URL: http://srh:80
UPSTASH_REDIS_REST_TOKEN: ${{ env.SRH_TOKEN }}
```
A huge thanks goes out to [Scott](https://hiett.dev/) for creating this project,
and for his continued efforts to keep it up to date with Upstash.
# Get Started
Source: https://upstash.com/docs/redis/sdks/ts/getstarted
`@upstash/redis` is written in Deno and can be imported from
[deno.land](https://deno.land)
```ts
import { Redis } from "https://deno.land/x/upstash_redis/mod.ts";
```
We transpile the package into an npm compatible package as well:
```bash
npm install @upstash/redis
```
```bash
yarn add @upstash/redis
```
```bash
pnpm add @upstash/redis
```
## Basic Usage:
```ts
import { Redis } from "@upstash/redis"
const redis = new Redis({
url: ,
token: ,
})
// string
await redis.set('key', 'value');
let data = await redis.get('key');
console.log(data)
await redis.set('key2', 'value2', {ex: 1});
// sorted set
await redis.zadd('scores', { score: 1, member: 'team1' })
data = await redis.zrange('scores', 0, 100 )
console.log(data)
// list
await redis.lpush('elements', 'magnesium')
data = await redis.lrange('elements', 0, 100 )
console.log(data)
// hash
await redis.hset('people', {name: 'joe'})
data = await redis.hget('people', 'name' )
console.log(data)
// sets
await redis.sadd('animals', 'cat')
data = await redis.spop('animals', 1)
console.log(data)
```
# Overview
Source: https://upstash.com/docs/redis/sdks/ts/overview
`@upstash/redis` is an HTTP/REST based Redis client for TypeScript, built on top
of [Upstash REST API](https://docs.upstash.com/features/restapi).
[](https://github.com/upstash/upstash-redis/actions/workflows/tests.yaml)
You can find the Github Repository [here](https://github.com/upstash/upstash-redis).
It is the only connectionless (HTTP based) Redis client and designed for:
* Serverless functions (AWS Lambda ...)
* Cloudflare Workers (see
[the example](https://github.com/upstash/upstash-redis/tree/master/examples/cloudflare-workers))
* Fastly Compute\@Edge (see
[the example](https://github.com/upstash/upstash-redis/tree/master/examples/fastly))
* Next.js, Jamstack ...
* Client side web/mobile applications
* WebAssembly
* and other environments where HTTP is preferred over TCP.
See
[the list of APIs](https://docs.upstash.com/features/restapi#rest---redis-api-compatibility)
supported.
# Auto-Pipelining
Source: https://upstash.com/docs/redis/sdks/ts/pipelining/auto-pipeline
### Auto Pipelining
Auto pipelining allows you to use the Redis client as usual
while in the background it tries to send requests in batches
whenever possible.
In a nutshell, the client will accumulate commands in a pipeline
and wait for a short amount of time for more commands to arrive.
When there are no more commands, it will execute them as a batch.
To enable the feature, simply pass `enableAutoPipelining: true`
when creating the Redis client:
```ts Redis
import { Redis } from "@upstash/redis";
const redis = Redis.fromEnv({
latencyLogging: false,
enableAutoPipelining: true
});
```
```ts fromEnv
import { Redis } from "@upstash/redis";
const redis = new Redis({
url: ,
token: ,
enableAutoPipelining: true
})
```
This is especially useful in cases when we want to make async
requests or when we want to make requests in batches.
```ts
import { Redis } from "@upstash/redis";
const redis = Redis.fromEnv({
latencyLogging: false,
enableAutoPipelining: true
});
// async call to redis. Not executed right away, instead
// added to the pipeline
redis.hincrby("Brooklyn", "visited", 1);
// making requests in batches
const brooklynInfo = Promise.all([
redis.hget("Brooklyn", "coordinates"),
redis.hget("Brooklyn", "population")
]);
// when we call await, the three commands are executed
// as a pipeline automatically. A single PIPELINE command
// is executed instead of three requests and the results
// are returned:
const [ coordinates, population ] = await brooklynInfo;
```
The benefit of auto pipelining is that it reduces the number
of HTTP requests made like pipelining and transaction while
being extremely simple to enable and use. It's especially
useful in cases like Vercel Edge and [Cloudflare Workers, where the number of
simultaneous requests is limited by 6](https://developers.cloudflare.com/workers/platform/limits/#account-plan-limits).
To learn more about how auto pipelining can be utilized in a
project, see
[the auto-pipeline example project under `upstash-redis` repository](https://github.com/upstash/upstash-redis/tree/main/examples/auto-pipeline)
### How it Works
For auto pipeline to work, the client keeps an active pipeline
and adds incoming commands to this pipeline. After the command
is added to the pipeline, execution of the pipeline is delayed
by releasing the control of the Node thread.
The pipeline executes when one of these two conditions are met:
No more commands are being added or at least one of the commands
added is being 'awaited'.
This means that if you are awaiting every time you run a command,
you won't benefit much from auto pipelining since each await will
trigger a pipeline:
```ts
const foo = await redis.get("foo") // makes a PIPELINE call
const bar = await redis.get("bar") // makes another PIPELINE call
```
In these cases, we suggest using `Promise.all`:
```ts
// makes a single PIPELINE call:
const [ foo, bar ] = await Promise.all([
redis.get("foo"),
redis.get("bar")
])
```
In addition to resulting in a single PIPELINE call, the commands
in `Promise.all` are executed in the order they are written!
# Pipeline & Transaction
Source: https://upstash.com/docs/redis/sdks/ts/pipelining/pipeline-transaction
### Pipeline
Pipelining commands allows you to send a single http request with multiple
commands. Keep in mind, that the execution of pipelines is not atomic and the
execution of other commands can interleave.
```ts
import { Redis } from "@upstash/redis";
const redis = new Redis({
/* auth */
});
const p = redis.pipeline();
// Now you can chain multiple commands to create your pipeline:
p.set("key", 2);
p.incr("key");
// or inline:
p.hset("key2", "field", { hello: "world" }).hvals("key2");
// Execute the pipeline once you are done building it:
// `exec` returns an array where each element represents the response of a command in the pipeline.
// You can optionally provide a type like this to get a typed response.
const res = await p.exec<[Type1, Type2, Type3]>();
```
For more information about pipelines using REST see
[here](https://blog.upstash.com/pipeline).
If you wish to benefit from pipeline automatically,
you can simply enable auto-pipelining to make your redis client
handle the commands in batches in the background. See
[the Auto-pipelining page](https://docs.upstash.com/redis/sdks/ts/pipelining/auto-pipeline).
### Transaction
Remember that the pipeline is able to send multiple commands at once but
can't execute them atomically. With transactions, you can make the commands
execute atomically.
```ts
import { Redis } from "@upstash/redis";
const redis = new Redis({
/* auth */
});
const p = redis.multi();
p.set("key", 2);
p.incr("key");
// or inline:
p.hset("key2", "field", { hello: "world" }).hvals("key2");
// execute the transaction
const res = await p.exec<[Type1, Type2, Type3]>();
```
# Retries
Source: https://upstash.com/docs/redis/sdks/ts/retries
By default `@upstash/redis` will retry sending you request when network errors
occur. It will retry 5 times with a backoff of
`(retryCount) => Math.exp(retryCount) * 50` milliseconds.
You can customize this in the `Redis` constructor:
```ts
new Redis({
url: UPSTASH_REDIS_REST_URL,
token: UPSTASH_REDIS_REST_TOKEN,
retry: {
retries: 5,
backoff: (retryCount) => Math.exp(retryCount) * 50,
},
});
```
The exact type definition can be found
[here](https://github.com/upstash/upstash-redis/blob/4948b049e0d580d1de0a4cbfeac5565d7e035cc4/pkg/http.ts#LL31C1-L49C5).
# Troubleshooting
Source: https://upstash.com/docs/redis/sdks/ts/troubleshooting
## ReferenceError: fetch is not defined
#### Problem
If you are running on nodejs v17 and earlier, fetch will not be natively
supported. Platforms like Vercel, Netlify, Deno, Fastly etc. provide a polyfill
for you. But if you are running on bare node, you need to add a polyfill.
#### Solution
```bash
npm i isomorphic-fetch
```
```ts
import { Redis } from "@upstash/redis";
import "isomorphic-fetch";
const redis = new Redis({
/*...*/
});
```
## Hashed Response
The response from a server is not what you expect but looks like a hash?
```ts
await redis.set("key", "value");
const data = await redis.get("key");
console.log(data);
// dmFsdWU=
```
#### Problem
By default `@upstash/redis` will request responses from the server to be base64
encoded. This is to prevent issues with some edge cases when storing data where
the http response fails to be deserialized using `res.json()`
This solves the problem for almost all edge cases, but it can cause new issues.
#### Solution
You can disable this behavior by setting `responseEncoding` to `false` in the
options.
```ts
const redis = new Redis({
// ...
responseEncoding: false,
});
```
This should no longer be necessary, but if you are still experiencing issues
with this, please let us know:
* [Discord](https://discord.gg/w9SenAtbme)
* [X](https://x.com/upstash)
* [GitHub](https://github.com/upstash/upstash-redis/issues/new)
## Large numbers are returned as string
You are trying to load a large number and it is returned as a string instead.
```ts
await redis.set("key", "101600000000150081467");
const res = await redis("get");
// "101600000000150081467"
```
#### Problem
Javascript can not handle numbers larger than `2^53 -1` safely and would return
wrong results when trying to deserialize them. In these cases the default
deserializer will return them as string instead. This might cause a mismatch
with your custom types.
#### Solution
Please be aware that this is a limitation of javascript and take special care
when handling large numbers.
# Unexpected Increase in Command Count
Source: https://upstash.com/docs/redis/troubleshooting/command_count_increases_unexpectedly
### Symptom
You notice an increasing command count for your Redis database in the Upstash Console, even when there are no connected clients.
### Diagnosis
The Upstash Console interacts with your Redis database to provide its functionality, which can result in an increased command count. This behavior is normal and expected. Here's a breakdown of why this occurs:
1. **Data Browser functionality:**
The Data Browser tab sends various commands to list and display your keys, including:
* SCAN: To iterate through the keyspace
* GET: To retrieve values for keys
* TTL: To check the time-to-live for keys
2. **Rate Limiting check:**
The Console checks if your database is being used for Rate Limiting. This involves sending EXISTS commands for rate limiting-related keys.
3. **Other Console features:**
Additional features in the Console may send commands to your database to retrieve or display information.
### Verification
You can use the Monitor tab in the Upstash Console to observe which commands are being sent by the Console itself. This can help you distinguish between Console-generated commands and those from your application or other clients.
Also, Usage tab contains 'Top Commands Usage' graph which shows the exact command history.
### Conclusion
The increasing command count you're seeing is likely due to the Console's normal operations and should not be a cause for concern. These commands do not significantly impact your database's performance or your usage limits.
If you have any further questions or concerns about command usage, please don't hesitate to contact Upstash support.
# ERR DB capacity quota exceeded
Source: https://upstash.com/docs/redis/troubleshooting/db_capacity_quota_exceeded
### Symptom
The client gets an exception similar to:
```
ReplyError: ERR DB capacity quota exceeded
```
### Diagnosis
Your total database size exceeds the max data size limit of your current plan. When this limit is reached,
write requests may be rejected. Read and delete requests will not be affected.
### Solution-1
You can manually delete some entries to allow further writes. Additionally you
can consider setting TTL (expiration time) for your keys or enable
[eviction](../features/eviction) for your database.
### Solution-2
You can upgrade your database to Pro for higher limits.
# Error read ECONNRESET
Source: https://upstash.com/docs/redis/troubleshooting/econn_reset
### Symptom
The client can not connect to the database throwing an exception similar to:
```
[ioredis] Unhandled error event: Error: read ECONNRESET
at TCP.onStreamRead (node:internal/stream_base_commons:211:20)
```
### Diagnosis
The server is TLS enabled but your connection (client) is not.
### Solution
Check your connection parameters and ensure you enable TLS.
If you are using a Redis URL then it should start with `rediss://`.
You can copy the correct client configuration from Upstash console clicking on
**Redis Connect** button.
# WRONGPASS invalid or missing auth token
Source: https://upstash.com/docs/redis/troubleshooting/http_unauthorized
### Symptom
The database rejects your request with an error similar to:
```
UpstashError: WRONGPASS invalid or missing auth token
```
### Diagnosis
The server rejects your request because the auth token is missing or invalid.
Most likely you have forgotten to set it in your environment variables, or you
are using a wrong token.
The connection password can only be used in traditional Redis clients. If you
want to connect over HTTP, you need to use the HTTP auth token.
### Solution
1. Check that you have set the `UPSTASH_REDIS_REST_TOKEN` in your environment
variables and it is loaded correctly by your application at runtime.
2. Make sure you are using the correct HTTP auth token. You can copy the correct
client configuration from the
[Upstash console](https://console.upstash.com/redis) by copying the snippet
from the `Connect to your database` -> `@upstash/redis` tab
Or scroll further down to the `REST API` section and copy the
`UPSTASH_REDIS_REST_URL` and `UPSTASH_REDIS_REST_TOKEN` from there.
# ERR max concurrent connections exceeded
Source: https://upstash.com/docs/redis/troubleshooting/max_concurrent_connections
### Symptom
New clients can not connect to the database throwing an exception similar to:
```
"message" : "[ioredis] Unhandled error event:
ReplyError: ERR max concurrent connections exceeded\r
at Object.onceWrapper (events.js:286:20)\r
at Socket.emit (events.js:203:15)\r at Socket.EventEmitter.emit (domain.js:448:20)\r
at TCPConnectWrap.afterConnect [as oncomplete] (net.js:1093:10)\n"
```
### Diagnosis
You have reached the concurrent connection limit.
### Solution-1
You need to manage connections more efficiently. If you are using serverless
functions, you can create the Redis client inside the function and close the
connection when you are done with the database as below.
This solution may have a latency overhead (about 4 ms). See [the blog
post](https://blog.upstash.com/serverless-database-connections) for more.
```javascript
exports.handler = async (event) => {
const client = new Redis(process.env.REDIS_URL);
/*
do stuff with redis
*/
await client.quit();
/*
do other stuff
*/
return {
response: "response",
};
};
```
### Solution-2
You can use [@upstash/redis](https://github.com/upstash/upstash-redis) client
which is REST based so it does not have any connection related problems.
### Solution-3
You can upgrade your database to Pro for higher limits.
See [the blog post](https://blog.upstash.com/serverless-database-connections)
about the database connections in serverless functions.
# ERR max daily request limit exceeded
Source: https://upstash.com/docs/redis/troubleshooting/max_daily_request_limit
### Symptom
The client gets an exception similar to:
```
ReplyError: ERR max daily request limit exceeded
```
### Diagnosis
Your database exceeds the max daily request count limit.
### Solution-1
You can refactor your application to send less number of commands.
### Solution-2
You can upgrade your database to a paid plan, such as pay-as-you-go or a fixed plan
by entering a payment method. When you entered your credit card, your database will be upgraded
automatically.
See [here](../howto/upgradedatabase) for more information.
# ERR max key size exceeded
Source: https://upstash.com/docs/redis/troubleshooting/max_key_size_exceeded
### Symptom
The client gets an exception similar to:
```
ReplyError: ERR max key size exceeded. Limit: X bytes, Actual: Z bytes
```
### Diagnosis
Size of the key in the request exceeds the max key size limit, which is `32Kb`.
### Solution
This is a hardcoded limit and cannot be configured per database. You should
reduce the key size.
# ERR max single record size exceeded
Source: https://upstash.com/docs/redis/troubleshooting/max_record_size_exceeded
### Symptom
The client gets an exception similar to:
```
ReplyError: ERR max single record size exceeded
```
### Diagnosis
An entry size exceeds the max record size limit which is `100Mb` for "Free" and
"Pay as you go" databases. You may reach this limit either by inserting a single
huge value or appending many small values to an entry. This entry can be a
String, List, Set, Hash etc. Read (`GET`, `LRANGE`, `HMGET`, `ZRANGE` etc) and
delete (`DEL`, `LPOP`, `HDEL`, `SREM` etc) requests will not be affected.
### Solution-1
You can split your data into smaller chunks and store them as separate entries
with different keys.
### Solution-2
You can upgrade your database to Pro as it has higher limits. Also
you can submit quota increase request in the console or contact
[support@upstash.com](mailto:support@upstash.com) about the options with higher max record size limit.
# ERR max request size exceeded
Source: https://upstash.com/docs/redis/troubleshooting/max_request_size_exceeded
### Symptom
The client gets an exception similar to:
```
ReplyError: ERR max request size exceeded
```
### Diagnosis
Your command exceeds the max request size which is `1Mb` for "Free" and "Pay as
you go" databases.
### Solution-1
You can split your data into smaller chunks and send them in separate commands.
### Solution-2
You can upgrade your database to Pro as it has higher limits. Also
you can submit quota increase request in the console or you can contact
[support@upstash.com](mailto:support@upstash.com) about the options with higher max request size limit.
max-request-size-limit is about the size of a single request. Your data
structure (like list, set) can exceed the max request size limit without any
problem. If you try to load all elements in the list with a single request
then it can throw the max-request-size-limit exception.
# ERR max requests limit exceeded
Source: https://upstash.com/docs/redis/troubleshooting/max_requests_limit
### Symptom
The client gets an exception similar to:
```
ReplyError: ERR max requests limit exceeded.
```
### Diagnosis
Your database exceeds the max monthly request count limit.
### Solution-1
You can refactor your application to send less number of commands.
### Solution-2
You can upgrade your database to a paid plan, such as pay-as-you-go or a fixed plan
by entering a payment method. When you entered your credit card, your database will be upgraded
automatically.
See [here](../howto/upgradedatabase) for more information.
# NOAUTH Authentication Required
Source: https://upstash.com/docs/redis/troubleshooting/no_auth
### Symptom
The client can not connect to the database throwing an exception similar to:
```
[ioredis] Unhandled error event:
ReplyError: NOAUTH Authentication required
```
### Diagnosis
The server does not let you connect because the password is missing in your
connection parameters.
### Solution
Check your connection parameters and ensure they contain the password. If you
are using ioredis (Redis client) with a Redis URL, check the URL format. ioredis
requires a colon before the password. The format for IORedis - TLS enabled
```
rediss://:YOUR_PASSWORD@YOUR_ENDPOINT:YOUR_PORT
```
The format for IORedis - TLS disabled
```
redis://:YOUR_PASSWORD@YOUR_ENDPOINT:YOUR_PORT
```
You can copy the correct client configuration from Upstash console clicking on
**Redis Connect** button.
# ERR XReadGroup is cancelled
Source: https://upstash.com/docs/redis/troubleshooting/stream_pel_limit
### Symptom
The client gets an exception similar to:
```
ReplyError: ERR XReadGroup is cancelled. Pending Entries List limit per consumer is about to be reached. Limit: 1000, Current PEL size: 90, Requested Read: 20, Key: mstream, Group: group1, Consumer: consumer1.
```
### Diagnosis
Pending Entries List of the stream for the consumer is full. For each consumer
in a consumer group, there is a pending entries list. This list keeps the
messages that are delivered to a consumer but not yet acknowledged via
[XACK](https://redis.io/commands/xack/). This list is populated via
[XREADGROUP](https://redis.io/commands/xreadgroup/).
### Solution
Acknowledge the consumed messages via [XACK](https://redis.io/commands/xack/)
from the list of the associated group and consumer.
# Deploy a Serverless API with AWS CDK and AWS Lambda
Source: https://upstash.com/docs/redis/tutorials/api_with_cdk
You can find the project source code on GitHub.
In this tutorial, we will implement a Serverless API using AWS Lambda and we
will deploy it using AWS CDK. We will use Typescript as the CDK language. It
will be a view counter where we keep the state in Redis.
### What is AWS CDK?
AWS CDK is an interesting project which allows you to provision and deploy AWS
infrastructure with code. Currently TypeScript, JavaScript, Python, Java,
C#/.Net and Go are supported. You can compare AWS CDK with following technologies:
* AWS CloudFormation
* AWS SAM
* Serverless Framework
The above projects allows you to set up the infrastructure with configuration
files (yaml, json) while with AWS CDK, you set up the resources with code. For
more information about CDK see the related
[AWS Docs](https://docs.aws.amazon.com/cdk/latest/guide/home.html).
### Prerequisites
* Complete all steps in [Getting started with the AWS CDK](https://docs.aws.amazon.com/cdk/v2/guide/getting_started.html)
### Project Setup
Create and navigate to a directory named `counter-cdk`. The CDK CLI uses this directory name to name things in your CDK code, so if you decide to use a different name, don't forget to make the appropriate changes when applying this tutorial.
```shell
mkdir counter-cdk && cd counter-cdk
```
Initialize a new CDK project.
```shell
cdk init app --language typescript
```
Install `@upstash/redis`.
```shell
npm install @upstash/redis
```
### Counter Function Setup
Create `/api/counter.ts`.
```ts /api/counter.ts
import { Redis } from '@upstash/redis';
const redis = Redis.fromEnv();
export const handler = async function() {
const count = await redis.incr("counter");
return {
statusCode: 200,
body: JSON.stringify('Counter: ' + count),
};
};
```
### Counter Stack Setup
Update `/lib/counter-cdk-stack.ts`.
```ts /lib/counter-cdk-stack.ts
import * as cdk from 'aws-cdk-lib';
import { Construct } from 'constructs';
import * as lambda from 'aws-cdk-lib/aws-lambda';
import * as nodejs from 'aws-cdk-lib/aws-lambda-nodejs';
export class CounterCdkStack extends cdk.Stack {
constructor(scope: Construct, id: string, props?: cdk.StackProps) {
super(scope, id, props);
const counterFunction = new nodejs.NodejsFunction(this, 'CounterFunction', {
entry: 'api/counter.ts',
handler: 'handler',
runtime: lambda.Runtime.NODEJS_20_X,
environment: {
UPSTASH_REDIS_REST_URL: process.env.UPSTASH_REDIS_REST_URL || '',
UPSTASH_REDIS_REST_TOKEN: process.env.UPSTASH_REDIS_REST_TOKEN || '',
},
bundling: {
format: nodejs.OutputFormat.ESM,
target: "node20",
nodeModules: ['@upstash/redis'],
},
});
const counterFunctionUrl = counterFunction.addFunctionUrl({
authType: lambda.FunctionUrlAuthType.NONE,
});
new cdk.CfnOutput(this, "counterFunctionUrlOutput", {
value: counterFunctionUrl.url,
})
}
}
```
### Database Setup
Create a Redis database using [Upstash Console](https://console.upstash.com) or [Upstash CLI](https://github.com/upstash/cli) and export `UPSTASH_REDIS_REST_URL` and `UPSTASH_REDIS_REST_TOKEN` to your environment.
```shell
export UPSTASH_REDIS_REST_URL=
export UPSTASH_REDIS_REST_TOKEN=
```
### Deploy
Run in the top folder:
```shell
cdk synth
cdk bootstrap
cdk deploy
```
Visit the output URL.
# Autocomplete API with Serverless Redis
Source: https://upstash.com/docs/redis/tutorials/auto_complete_with_serverless_redis
This tutorial implements an autocomplete API powered by serverless Redis. See
[the demo](https://auto-complete-example.vercel.app/) and
[API endpoint](https://wfgz7cju24.execute-api.us-east-1.amazonaws.com/query?term=ca)
and
[the source code](https://github.com/upstash/examples/tree/main/examples/auto-complete-api).
We will keep country names in a Redis Sorted set. In Redis sorted set, elements
with the same score are sorted lexicographically. So in our case, all country
names will have the same score, 0. We keep all prefixes of country and use ZRANK
to find the terms to suggest. See
[this blog post](https://oldblog.antirez.com/post/autocomplete-with-redis.html)
for the details of the algorithm.
### Step 1: Project Setup
I will use Serverless framework for this tutorial. You can also use [AWS
SAM](/redis/tutorials/using_aws_sam)
If you do not have it already install serverless framework via:
`npm install -g serverless`
In any folder run `serverless` as below:
```text
>> serverless
Serverless: No project detected. Do you want to create a new one? Yes
Serverless: What do you want to make? AWS Node.js
Serverless: What do you want to call this project? test-upstash
Project successfully created in 'test-upstash' folder.
You can monitor, troubleshoot, and test your new service with a free Serverless account.
Serverless: Would you like to enable this? No
You can run the āserverlessā command again if you change your mind later.
```
Inside the project folder create a node project with the command:
```
npm init
```
Then install the redis client with:
```
npm install ioredis
```
### Step 2: API Implementation
Edit handler.js file as below. See
[the blog post](https://oldblog.antirez.com/post/autocomplete-with-redis.html)
for the details of the algorithm.
```javascript
var Redis = require("ioredis");
if (typeof client === "undefined") {
var client = new Redis(process.env.REDIS_URL);
}
const headers = {
"Access-Control-Allow-Origin": "*",
"Access-Control-Allow-Credentials": true,
};
module.exports.query = async (event, context, callback) => {
if (!event.queryStringParameters || !event.queryStringParameters.term) {
return {
statusCode: 400,
headers: headers,
body: JSON.stringify({
message: "Invalid parameters. Term needed as query param.",
}),
};
}
let term = event.queryStringParameters.term.toUpperCase();
let res = [];
let rank = await client.zrank("terms", term);
if (rank != null) {
let temp = await client.zrange("terms", rank, rank + 100);
for (const el of temp) {
if (!el.startsWith(term)) {
break;
}
if (el.endsWith("*")) {
res.push(el.substring(0, el.length - 1));
}
}
}
return {
statusCode: 200,
headers: headers,
body: JSON.stringify({
message: "Query:" + event.queryStringParameters.term,
result: res,
}),
};
};
```
### Step 3: Create database on Upstash
If you do not have one, create a database following this
[guide](../overall/getstarted). Copy the Redis URL by clicking `Redis Connect`
button inside database page. Copy the URL for ioredis as we use ioredis in our
application. Create .env file and paste your Redis URL:
```text
REDIS_URL=YOUR_REDIS_URL
```
In the next page, choose `Nodejs 12` as your runtime, `npm install` as your
build command, `node server` as your start command and `8080` as your port.
The next page configures your App Runner service. Set a name for your service.
Set your Redis URL that you copied from Upstash console as `REDIS_URL`
environment variable. Your Redis URL should be something like this:
`rediss://:d34baef614b6fsdeb01b25@us1-lasting-panther-33618.upstash.io:33618`
You can leave other settings as default.
Click on `Create and Deploy` at the next page. Your service will be ready in a
few minutes. Click on the default domain, you should see the page with a view
counter as [here](https://xmzuanrpf3.us-east-1.awsapprunner.com/).
### App Runner vs AWS Lambda
* AWS Lambda runs functions, App Runner runs applications. So with App Runner
you do not need to split your application to functions.
* App Runner is a more portable solution. You can move your application from App
Runner to any other container service.
* AWS Lambda price scales to zero, App Runner's does not. With App Runner you
need to pay for an at least one instance unless you pause the system.
App Runner is great alternative when you need more control on your serverless
runtime and application. Check out
[this video](https://www.youtube.com/watch?v=x_1X_4j16A4) to learn more about
App Runner.
# Session Management on Google Cloud Run with Serverless Redis
Source: https://upstash.com/docs/redis/tutorials/cloud_run_sessions
This tutorial shows how to manage user sessions on Google Cloud Run using Serverless Redis.
Developers are moving their apps to serverless architectures and one of the most
common questions is
[how to store user sessions](https://stackoverflow.com/questions/57711095/are-users-sessions-on-google-cloud-run-apps-directed-to-the-same-instance).
You need to keep your state and session data in an external data store because
serverless environments are stateless by design. Unfortunately most of the
databases are not serverless friendly. They do not support per-request pricing
or they require heavy and persistent connections. These also explain the
motivations why we built Upstash. Upstash is a serverless Redis database with
per-request pricing, durable storage.
In this article I will write a basic web application which will run on Google
Cloud Run and keep the user sessions in Upstash Redis. Google Cloud Run provides
Serverless Container service which is also stateless. Cloud Run is more powerful
than serverless functions (AWS Lambda, Cloud Functions) as you can run your own
container. But you can not guarantee that the same container instance will
process the requests of the same user. So you need to keep the user session in
an external storage. Redis is the most popular choice to keep the session data
thanks to its speed and simplicity. Upstash gives you the serverless Redis
database which fits perfectly to your serverless stack.
If you want to store your session data manually on Redis, check
[here](https://upstash.com/docs/redis/tutorials/using_google_cloud_functions). But in
this article I will use [Express session](https://github.com/expressjs/session)
middleware which can work with Redis for user session management.
Here is the [live demo.](https://cloud-run-sessions-dr7fcdmn3a-uc.a.run.app)
Here is the
[source code](https://github.com/upstash/examples/tree/master/examples/cloud-run-sessions)
## The Stack
Serverless processing: Google Cloud Run
Serverless data: Upstash
Web framework: Express
## Project Setup
Create a directory for your project:
```
mkdir cloud-run-sessions
cd cloud-run-sessions
```
Create a node project and install dependencies:
```
npm init
npm install express redis connect-redis express-session
```
Create a Redis DB from [Upstash](https://console.upstash.com). In the database
details page, click the Connect button, copy the connection code (Node.js
node-redis).
If you do not have it already, install Google Cloud SDK as described
[here.](https://cloud.google.com/sdk/docs/install) Set the project and enable
Google Run and Build services:
```
gcloud config set project cloud-run-sessions
gcloud services enable run.googleapis.com
gcloud services enable cloudbuild.googleapis.com
```
## The Code
Create index.js and update as below:
```javascript
var express = require("express");
var parseurl = require("parseurl");
var session = require("express-session");
const redis = require("redis");
var RedisStore = require("connect-redis")(session);
var client = redis.createClient({
// REPLACE HERE
});
var app = express();
app.use(
session({
store: new RedisStore({ client: client }),
secret: "forest squirrel",
resave: false,
saveUninitialized: true,
})
);
app.use(function (req, res, next) {
if (!req.session.views) {
req.session.views = {};
}
// get the url pathname
var pathname = parseurl(req).pathname;
// count the views
req.session.views[pathname] = (req.session.views[pathname] || 0) + 1;
next();
});
app.get("/", function (req, res, next) {
res.send("you viewed this page " + req.session.views["/"] + " times");
});
app.get("/foo", function (req, res, next) {
res.send("you viewed this page " + req.session.views["/foo"] + " times");
});
app.get("/bar", function (req, res, next) {
res.send("you viewed this page " + req.session.views["/bar"] + " times");
});
app.listen(8080, function () {
console.log("Example app listening on port 8080!");
});
```
Run the app: `node index.js`
Check [http://localhost:3000/foo](http://localhost:3000/foo) in different
browsers to validate it keeps the session.
Add the start script to your `package.json`:
```json
"scripts": {
"test": "echo \"Error: no test specified\" && exit 1",
"start": "node index"
}
```
## Build
Create a Docker file (Dockerfile) in the project folder as below:
```
# Use the official lightweight Node.js 12 image.
# https://hub.docker.com/_/node
FROM node:12-slim
# Create and change to the app directory.
WORKDIR /usr/src/app
# Copy application dependency manifests to the container image.
# A wildcard is used to ensure both package.json AND package-lock.json are copied.
# Copying this separately prevents re-running npm install on every code change.
COPY package*.json ./
# Install dependencies.
RUN npm install
# Copy local code to the container image.
COPY . ./
# Run the web service on container startup.
CMD [ "npm", "start" ]
```
Build your container image:
```
gcloud builds submit --tag gcr.io/cloud-run-sessions/main
```
List your container images: `gcloud container images list`
Run the container locally:
```
gcloud auth configure-docker
docker run -d -p 8080:8080 gcr.io/cloud-run-sessions/main:v0.1
```
In case you have an issue on docker run, check
[here](https://cloud.google.com/container-registry/docs/troubleshooting).
## Deploy
Run:
```
gcloud run deploy cloud-run-sessions \
--image gcr.io/cloud-run-sessions/main:v0.1 \
--platform managed \
--region us-central1 \
--allow-unauthenticated
```
This command should give you
[the URL of your application](https://cloud-run-sessions-dr7fcdmn3a-uc.a.run.app)
as below:
```
Deploying container to Cloud Run service [cloud-run-sessions] in project [cloud-run-sessions] region [us-central1]
ā Deploying... Done.
ā Creating Revision...
ā Routing traffic...
ā Setting IAM Policy...
Done.
Service [cloud-run-sessions] revision [cloud-run-sessions-00006-dun] has been deployed and is serving 100 percent of traffic.
Service URL: https://cloud-run-sessions-dr7fcdmn3a-uc.a.run.app
```
## Cloud Run vs Cloud Functions
I have developed two small prototypes with both. Here my impression:
* Simplicity: Cloud functions are simpler to deploy as it does not require any
container building step.
* Portability: Cloud Run leverages your container, so anytime you can move your
application to any containerized system. This is a plus for Cloud Run.
* Cloud Run looks more powerful as it runs your own container with more
configuration options. It also allows running longer tasks (can be extended to
60 minutes)
* Cloud Run looks more testable as you can run the container locally. Cloud
Functions require a simulated environment.
Personally, I see Cloud Functions as a pure serverless solution where Cloud Run
is a hybrid solution. I would choose Cloud functions for simple, self contained
tasks or event driven solutions. If my use case is more complex with
portability/testability requirements, then I would choose Cloud Run.
# Cloudflare Workers with Websockets and Redis
Source: https://upstash.com/docs/redis/tutorials/cloudflare_websockets_redis
# Use Redis in Cloudflare Workers
Source: https://upstash.com/docs/redis/tutorials/cloudflare_workers_with_redis
You can find the project source code on GitHub.
This tutorial showcases using Redis with REST API in Cloudflare Workers. We will
write a sample edge function (Cloudflare Workers) which will show a custom
greeting depending on the location of the client. We will load the greeting
message from Redis so you can update it without touching the code.
### Why Upstash?
* Cloudflare Workers does not allow TCP connections. Upstash provides REST API
on top of the Redis database.
* Upstash is a serverless offering with per-request pricing which fits for edge
and serverless functions.
* Upstash Global database provides low latency all over the world.
### Prerequisites
1. Install the Cloudflare Wrangler CLI with `npm install wrangler --save-dev`
### Project Setup
Create a Cloudflare Worker with the following options:
```shell
ā tutorials > ā npx wrangler init
ā Create an application with Cloudflare Step 1 of 3
ā
ā In which directory do you want to create your application?
ā dir ./greetings-cloudflare
ā
ā What would you like to start with?
ā category Hello World example
ā
ā Which template would you like to use?
ā type Hello World Worker
ā
ā Which language do you want to use?
ā lang TypeScript
ā
ā Copying template files
ā files copied to project directory
ā
ā Updating name in `package.json`
ā updated `package.json`
ā
ā Installing dependencies
ā installed via `npm install`
ā
ā° Application created
ā Configuring your application for Cloudflare Step 2 of 3
ā
ā Installing @cloudflare/workers-types
ā installed via npm
ā
ā Adding latest types to `tsconfig.json`
ā added @cloudflare/workers-types/2023-07-01
ā
ā Retrieving current workerd compatibility date
ā compatibility date 2024-10-22
ā
ā Do you want to use git for version control?
ā no git
ā
ā° Application configured
```
Install Upstash Redis:
```shell
cd greetings-cloudflare
npm install @upstash/redis
```
### Database Setup
Create a Redis database using [Upstash Console](https://console.upstash.com) or [Upstash CLI](https://github.com/upstash/cli) and copy the `UPSTASH_REDIS_REST_URL` and `UPSTASH_REDIS_REST_TOKEN` into your `wrangler.toml` file.
```toml wrangler.toml
# existing config
[vars]
UPSTASH_REDIS_REST_URL =
UPSTASH_REDIS_REST_TOKEN =
```
Using CLI Tab in the Upstash Console, add some greetings to your database:
### Greetings Function Setup
Update `src/index.ts`:
```typescript src/index.ts
import { Redis } from '@upstash/redis/cloudflare';
type RedisEnv = {
UPSTASH_REDIS_REST_URL: string;
UPSTASH_REDIS_REST_TOKEN: string;
};
export default {
async fetch(request: Request, env: RedisEnv) {
const redis = Redis.fromEnv(env);
const country = request.headers.get('cf-ipcountry');
if (country) {
const greeting = await redis.get(country);
if (greeting) {
return new Response(greeting);
}
}
return new Response('Hello!');
},
};
```
The code tries to find out the user's location checking the "cf-ipcountry"
header. Then it loads the corresponding greeting for that location using the Redis
REST API.
### Run Locally
Run the following command to start your dev session:
```shell
npx wrangler dev
```
Visit [localhost:8787](http://localhost:8787)
### Build and Deploy
Build and deploy your app to Cloudflare:
```shell
npx wrangler deploy
```
Visit the output url.
# Backendless Coin Price List with GraphQL API, Serverless Redis and Next.JS
Source: https://upstash.com/docs/redis/tutorials/coin_price_list
In this tutorial, we will develop a simple coin price list using GraphQL API of
Upstash. You can call the application `backendless` because we will access the
database directly from the client (javascript). See the
[code](https://github.com/upstash/examples/tree/master/examples/coin-price-list).
## Motivation
We want to give a use case where you can use the GraphQL API without any backend
code. The use case is publicly available read only data for web applications
where you need low latency. The data is updated frequently by another backend
application, you want your users to see the last updated data. Examples:
Leaderboards, news list, blog list, product list, top N items in the homepages.
### `1` Project Setup:
Create a Next application: `npx create-next-app`.
Install Apollo GraphQL client: `npm i @apollo/client`
### `2` Database Setup
If you do not have one, create a database following this
[guide](../overall/getstarted). Connect your database via Redis CLI and run:
```shell
rpush coins '{ "name" : "Bitcoin", "price": 56819, "image": "https://s2.coinmarketcap.com/static/img/coins/64x64/1.png"}' '{ "name" : "Ethereum", "price": 2130, "image": "https://s2.coinmarketcap.com/static/img/coins/64x64/1027.png"}' '{ "name" : "Cardano", "price": 1.2, "image": "https://s2.coinmarketcap.com/static/img/coins/64x64/2010.png"}' '{ "name" : "Polkadot", "price": 35.96, "image": "https://s2.coinmarketcap.com/static/img/coins/64x64/6636.png"}' '{ "name" : "Stellar", "price": 0.506, "image": "https://s2.coinmarketcap.com/static/img/coins/64x64/512.png"}'
```
### `3` Code
In the Upstash console, copy the read only access key in your API configuration
page (GraphQL Explorer > Configure API). In the `_app.js` create the Apollo
client and replace the your access key as below:
You need to use Read Only Access Key, because the key will be accessible
publicly.
```javascript
import "../styles/globals.css";
import {
ApolloClient,
ApolloProvider,
createHttpLink,
InMemoryCache,
} from "@apollo/client";
const link = createHttpLink({
uri: "https://graphql-us-east-1.upstash.io/",
headers: {
Authorization: "Bearer YOUR_ACCESS_TOKEN",
},
});
const client = new ApolloClient({
uri: "https://graphql-us-east-1.upstash.io/",
cache: new InMemoryCache(),
link,
});
function MyApp({ Component, pageProps }) {
return (
);
}
export default MyApp;
```
Edit `index.js` as below:
```javascript
import Head from "next/head";
import styles from "../styles/Home.module.css";
import { gql, useQuery } from "@apollo/client";
import React from "react";
const GET_COIN_LIST = gql`
query {
redisLRange(key: "coins", start: 0, stop: 6)
}
`;
export default function Home() {
let coins = [];
const { loading, error, data } = useQuery(GET_COIN_LIST);
if (!loading && !error) {
for (let x of data.redisLRange) {
let dd = JSON.parse(x);
coins.push(dd);
}
}
return (
Create Next App
Coin Price List
{!loading ? (
coins.map((item, ind) => (
{item.name}
${item.price}
))
) : (
)}
);
}
```
### `4` Run
Run your application locally: `npm run dev`
### `5` Live!
Go to [http://localhost:3000/](http://localhost:3000/) š
# Build a Leaderboard API At Edge using Cloudflare Workers and Redis
Source: https://upstash.com/docs/redis/tutorials/edge_leaderboard
This tutorial shows how to build a Leaderboard API At Edge using Cloudflare Workers and Redis.
With edge functions, it is possible to run your backend at the closest location
to your users. Cloudflare Workers and Fastly Compute\@Edge runs your function at
the closest location to your user using their CDN infrastructure.
In this article we will implement a very common web use case at Edge. We will
implement a leaderboard API without any backend servers, containers or even
serverless functions. We will just use edge functions. Leaderboard will have the
following APIs:
* addScore: Adds a score with the player's name. This will write the score to
the Upstash Redis directly from the Edge functions.
* getLeaderBoard: Returns the list of score-player pairs. This call will first
check the Edge cache. If the leaderboard does not exist at the Edge Cache then
it will fetch it from the Upstash Redis.
Edge caching is deprecated. Please use global database instead.
## Project Setup
In this tutorial, we will use Cloudflare Workers and Upstash. You can create a
free database from [Upstash Console](https://console.upstash.com). Then create a
Workers project using
[Wrangler](https://developers.cloudflare.com/workers/get-started/guide).
Install wrangler: `npm install -g @cloudflare/wrangler`
Authenticate: `wrangler login` or `wrangler config`
Then create a project: `wrangler generate edge-leaderboard`
Open `wrangler.toml`. Run `wrangler whoami` and copy/paste your account id to
your wrangler.toml.
Find your REST token from database details page in the
[Upstash Console](https://console.upstash.com). Copy/paste your token to your
wrangler toml as below:
```
name = "edge-leaderboard"
type = "javascript"
account_id = "REPLACE_YOUR_ACCOUNT_ID"
workers_dev = true
route = ""
zone_id = ""
[vars]
TOKEN = "REPLACE_YOUR_UPSTASH_REST_TOKEN"
```
## The Code
The only file we need is the Workers Edge function. Update the index.js as
below:
```javascript
addEventListener("fetch", (event) => {
event.respondWith(handleRequest(event.request));
});
async function handleRequest(request) {
if (request.method === "GET") {
return getLeaderboard();
} else if (request.method === "POST") {
return addScore(request);
} else {
return new Response("Invalid Request!");
}
}
async function getLeaderboard() {
let url =
"https://us1-full-bug-31874.upstash.io/zrevrange/scores/0/1000/WITHSCORES/?_token=" +
TOKEN;
let res = await fetch(new Request(url), {
cf: {
cacheTtl: 10,
cacheEverything: true,
cacheKey: url,
},
});
return res;
}
async function addScore(request) {
const { searchParams } = new URL(request.url);
let player = searchParams.get("player");
let score = searchParams.get("score");
let url =
"https://us1-full-bug-31874.upstash.io/zadd/scores/" +
score +
"/" +
player +
"?_token=" +
TOKEN;
let res = await fetch(url);
return new Response(await res.text());
}
```
We route the request to two methods: if it is a GET, we return the leaderboard.
If it is a POST, we read the query parameters and add a new score.
In the getLeaderboard() method, you will see we pass a cache configuration to
the fetch() method. It caches the result of the request at the Edge for 10
seconds.
## Test The API
In your project folder run `wrangler dev`. It will give you a local URL. You can
test your API with curl:
Add new scores:
```shell
curl -X POST http://127.0.0.1:8787\?player\=messi\&score\=13
curl -X POST http://127.0.0.1:8787\?player\=ronaldo\&score\=17
curl -X POST http://127.0.0.1:8787\?player\=benzema\&score\=18
```
Get the leaderboard:
```shell
curl -w '\n Latency: %{time_total}s\n' http://127.0.0.1:8787
```
Call the ācurl -w '\n Total: %{time_total}s\n'
[http://127.0.0.1:8787](http://127.0.0.1:8787)ā multiple times. You will see the
latency becomes very small with the next calls as the cached result comes from
the edge.
If you wait more than 10 seconds then you will see the latency becomes higher as
the cache is evicted and the function fetches the leaderboard from the Upstash
Redis again.
## Deploy The API
First change the type in the wrangler.toml to `webpack`
```
name = "edge-leaderboard"
type = "webpack"
```
Then, run `wrangler publish`. Wrangler will output the URL. If you want to
deploy to a custom domain see
[here](https://developers.cloudflare.com/workers/get-started/guide#optional-configure-for-deploying-to-a-registered-domain).
# Express Session with Serverless Redis
Source: https://upstash.com/docs/redis/tutorials/express_session
This tutorial shows how to use Upstash as the session storage of your Express application.
This tutorial shows how to use Serverless Redis as your session storage for your
Express Applications.
See the
[code](https://github.com/upstash/examples/tree/main/examples/express-session-with-redis)
### Step-1: Create Project
Create a folder for your project and run: `npm init`
### Step-2: Install Redis and Express
In your project folder run:
`npm install express redis connect-redis express-session`
### Step-3: Create a Redis (Upstash) Database For Free
Create a database as described [here](../overall/getstarted).
### Step-4: index.js
In Upstash console, click the `Connect` button, copy the connection code
(Node.js node-redis). Create index.js file as below and replace the Redis
connection part.
```javascript
var express = require("express");
var parseurl = require("parseurl");
var session = require("express-session");
const redis = require("redis");
var RedisStore = require("connect-redis")(session);
var client = redis.createClient({
// REPLACE HERE
});
var app = express();
app.use(
session({
store: new RedisStore({ client: client }),
secret: "forest squirrel",
resave: false,
saveUninitialized: true,
})
);
app.use(function (req, res, next) {
if (!req.session.views) {
req.session.views = {};
}
// get the url pathname
var pathname = parseurl(req).pathname;
// count the views
req.session.views[pathname] = (req.session.views[pathname] || 0) + 1;
next();
});
app.get("/foo", function (req, res, next) {
res.send("you viewed this page " + req.session.views["/foo"] + " times");
});
app.get("/bar", function (req, res, next) {
res.send("you viewed this page " + req.session.views["/bar"] + " times");
});
app.listen(3000, function () {
console.log("Example app listening on port 3000!");
});
```
### Step-5: Run the app
`node index.js`
### Step-6: Check your work
Open [http://localhost:3000/bar](http://localhost:3000/bar) and [http://localhost:3000/foo](http://localhost:3000/foo) in different
browsers. Check if the view-count is incrementing as expected.
### FAQ:
**There is a default session storage of express-session. Why do I need Redis?**
*Default session store loses the session data when the process crashes.
Moreover, it does not scale. You can not utilize multiple web servers to serve
your sessions.*
**Why Upstash?**
*You can use any Redis offering or self hosted one. But Upstash's serverless
approach with per-request-pricing will help you to minimize your cost with zero
maintenance.*
**How to configure the session storage?**
*See [here](https://github.com/expressjs/session#readme)*
# Serverless Golang API with Redis
Source: https://upstash.com/docs/redis/tutorials/goapi
This tutorial shows how to build a serverless API with Golang and Redis. The API
will simply count the page views and show it in JSON format.
### The Stack
* Serverless compute: AWS Lambda (Golang)
* Serverless data store: Redis via Upstash
* Deployment tool: AWS SAM
### Prerequisites:
* An AWS account for AWS Lambda functions.
* Install AWS SAM CLI tool as described here to create and deploy the project.
* An Upstash account for serverless Redis.
### Step 1: Init the Project
Run the sam init and then
* Select AWS Quick Start Templates
* Select 4 - go1.x
* Enter your project name: go-redis-example
* Select 1 - Hello World Example SAM will generate your project in a new folder.
### Step 2: Install a Redis Client
Our only dependency is redis client. Install go-redis via
`go get github.com/go-redis/redis/v8`
### Step 3: Create a Redis Database
Create a Redis database from Upstash console. Free tier should be enough. It is
pretty straight forward but if you need help, check
[getting started](../overall/getstarted) guide. In the database details page,
click the Connect button. You will need the endpoint and password in the next
step.
### Step 4: The function Code
Edit the hello-world>main.go as below:
```go
package main
import (
"context"
"encoding/json"
"github.com/aws/aws-lambda-go/events"
"github.com/aws/aws-lambda-go/lambda"
"github.com/go-redis/redis/v8"
"strconv"
)
var ctx = context.Background()
type MyResponse struct {
Count string `json:"count:"`
}
var rdb = redis.NewClient(&redis.Options{
Addr: "YOUR_REDIS_ENDPOINT",
Password: "YOUR_REDIS_PASSWORD",
DB: 0,
})
func handler(request events.APIGatewayProxyRequest) (events.APIGatewayProxyResponse, error) {
count, err := rdb.Incr(ctx, "count").Result()
if err != nil {
panic(err)
}
response := &MyResponse{
Count: strconv.FormatInt(count, 10),
}
body, err := json.Marshal(response)
return events.APIGatewayProxyResponse{
Headers: map[string]string{"Content-Type": "application/json"},
Body: string(body),
StatusCode: 200,
}, nil
}
func main() {
lambda.Start(handler)
}
```
Replace the "YOUR\_REDIS\_ENDPOINT" and "YOUR\_REDIS\_PASSWORD" with your database's
endpoint and password which you created in the Step 3. The code simply
increments a counter in Redis database and returns its value in json format.
### Step 5: Deployment
Now we are ready to deploy our API. First build it via `sam build`. Then run the
command `sam local start-api`. You can check your API locally on
[http://127.0.0.1:3000/hello](http://127.0.0.1:3000/hello)
If it is working, you can deploy your app to AWS by running `sam deploy --guided`.
Enter a stack name and pick your region. After confirming changes, the deployment
should begin. The command will output API Gateway endpoint URL, check the API in
your browser. You can also check your deployment on your AWS console. You will see
your function has been created.
Click on your function, you will see the code is uploaded and API Gateway
is configured.
### Notes
* Check the template.yaml file. You can add new functions and APIGateway
endpoints editing this file.
* It is a good practice to keep your Redis endpoint and password as environment
variable.
* You can use [serverless framework](https://www.serverless.com/) instead of AWS
SAM to deploy your function.
# Build a Serverless Histogram API with Redis
Source: https://upstash.com/docs/redis/tutorials/histogram
This tutorial shows how to build a histogram API with Redis.
While developing
[the latency benchmark for the serverless databases (DynamoDB, FaunaDB, Upstash)](https://blog.upstash.com/latency-comparison),
I wished there was an API where I will record the latency numbers and get the
histogram back. In this tutorial, I will build such an API where you can record
your latency values from any application. It will be a REST API with following
methods:
* record: Records numeric values into the histogram.
* get: Returns the histogram object.
### Motivation
I will show how easy to develop a generic API using AWS Lambda and Serverless
Redis.
See [code](https://github.com/upstash/examples/tree/master/examples/histogram-api).
### `1` Create a Redis (Upstash) Database
Create a database as [getting started](../overall/getstarted)
### `2` Serverless Project Setup
If you do not have it already install serverless framework via:
`npm install -g serverless`
In any folder run `serverless` as below:
```text
>> serverless
Serverless: No project detected. Do you want to create a new one? Yes
Serverless: What do you want to make? AWS Node.js
Serverless: What do you want to call this project? histogram-api
Project successfully created in 'histogram-api' folder.
You can monitor, troubleshoot, and test your new service with a free Serverless account.
Serverless: Would you like to enable this? No
You can run the āserverlessā command again if you change your mind later.
```
See [Using AWS SAM](/redis/tutorials/using_aws_sam), if you prefer AWS SAM
over Serverless Framework.
Inside the project folder create a node project with the command:
```
npm init
```
Then install the redis client and histogram library with:
```
npm install ioredis
npm install hdr-histogram-js
```
Update the `serverless.yml` as below. Copy your Redis URL from console and
replace below:
```yaml
service: histogram-api
frameworkVersion: "2"
provider:
name: aws
runtime: nodejs12.x
lambdaHashingVersion: 20201221
environment:
REDIS_URL: REPLACE_YOUR_URL_HERE
functions:
record:
handler: handler.record
events:
- httpApi:
path: /record
method: post
cors: true
get:
handler: handler.get
events:
- httpApi:
path: /get
method: get
cors: true
```
"
REDIS_PORT=6379
REDIS_PASSWORD=""
```
### Cache Setup
To use Upstash Redis as your caching driver, update the CACHE\_STORE in your .env file:
```shell .env
CACHE_STORE="redis"
REDIS_CACHE_DB="0"
```
## Creating a Todo App
First, we'll create a Todo model with its associated controller, factory, migration, and API resource files:
```shell
php artisan make:model Todo -cfmr --api
```
Next, we'll set up the database schema for our todos table with a simple structure including an ID, title, and timestamps:
```php database/migrations/2025_02_10_111720_create_todos_table.php
id();
$table->string('title');
$table->timestamps();
});
}
/**
* Reverse the migrations.
*/
public function down(): void
{
Schema::dropIfExists('todos');
}
};
```
We'll create a factory to generate fake todo data for testing and development:
```php database/factories/TodoFactory.php
*/
class TodoFactory extends Factory
{
/**
* Define the model's default state.
*
* @return array
*/
public function definition(): array
{
return [
'title' => $this->faker->sentence,
];
}
}
```
In the database seeder, we'll set up the creation of 50 sample todo items:
```php database/seeders/DatabaseSeeder.php
times(50)->create();
}
}
```
Run the migration to create the todos table in the database:
```shell
php artisan migrate
```
Seed the database with our sample todo items:
```shell
php artisan db:seed
```
Install the API package:
```shell
php artisan install:api
```
Set up the API routes for our Todo resource:
```php routes/api.php
*/
use HasFactory;
protected $fillable = ['title'];
}
```
Next, we'll update the methods in the TodoController to use caching:
```php app/Http/Controllers/TodoController.php
validate([
'title' => 'required|string|max:255',
]);
$todo = Todo::create($request->all());
// Invalidate the todos cache
Cache::forget(self::CACHE_KEY);
return response()->json($todo, Response::HTTP_CREATED);
}
/**
* Display the specified resource.
*/
public function show(Todo $todo): Todo
{
return Cache::flexible(
"todo.{$todo->id}",
self::CACHE_TTL,
function () use ($todo) {
return $todo;
}
);
}
/**
* Update the specified resource in storage.
*/
public function update(Request $request, Todo $todo): JsonResponse
{
$request->validate([
'title' => 'required|string|max:255',
]);
$todo->update($request->all());
// Invalidate both the collection and individual todo cache
Cache::forget(self::CACHE_KEY);
Cache::forget("todo.{$todo->id}");
return response()->json($todo);
}
/**
* Remove the specified resource from storage.
*/
public function destroy(Todo $todo): JsonResponse
{
$todo->delete();
// Invalidate both the collection and individual todo cache
Cache::forget(self::CACHE_KEY);
Cache::forget("todo.{$todo->id}");
return response()->json(null, Response::HTTP_NO_CONTENT);
}
}
```
Now we can test our methods with the following curl commands:
```shell
# Get all todos
curl http://todo-cache.test/api/todos
# Get a specific todo
curl http://todo-cache.test/api/todos/1
# Create a new todo
curl -X POST http://todo-cache.test/api/todos \
-H "Content-Type: application/json" \
-d '{"title":"New Todo"}'
# Update a todo
curl -X PUT http://todo-cache.test/api/todos/1 \
-H "Content-Type: application/json" \
-d '{"title":"Updated Todo"}'
# Delete a todo
curl -X DELETE http://todo-cache.test/api/todos/1
```
Visit Redis Data Browser in Upstash Console to see the cached data.
# Next.js with Redis
Source: https://upstash.com/docs/redis/tutorials/nextjs_with_redis
You can find the project source code on GitHub.
This tutorial uses Next.js App Router. If you want to use Pages Router, check out our [Pages Router tutorial](/redis/quickstarts/nextjs-pages-router).
This tutorial uses Redis as state store for a Next.js application. We simply add
a counter that pulls the data from Redis.
### Project Setup
Let's create a new Next.js application with App Router and install `@upstash/redis` package.
```shell
npx create-next-app@latest
cd my-app
npm install @upstash/redis
```
### Database Setup
Create a Redis database using [Upstash Console](https://console.upstash.com) or [Upstash CLI](https://github.com/upstash/cli) and copy the `UPSTASH_REDIS_REST_URL` and `UPSTASH_REDIS_REST_TOKEN` into your `.env` file.
```shell .env
UPSTASH_REDIS_REST_URL=
UPSTASH_REDIS_REST_TOKEN=
```
If you are using the Vercel & Upstash integration, you may use the following environment variables:
```shell .env
KV_REST_API_URL=
KV_REST_API_TOKEN=
```
### Home Page Setup
Update `/app/page.tsx`:
```tsx /app/page.tsx
import { Redis } from "@upstash/redis";
const redis = Redis.fromEnv();
export default async function Home() {
const count = await redis.incr("counter");
return (
Counter: {count}
)
}
```
### Run & Deploy
Run the app locally with `npm run dev`, check `http://localhost:3000/`
Deploy your app with `vercel`
You can also integrate your Vercel projects with Upstash using Vercel
Integration module. Check [this article](../howto/vercelintegration).
# Building a Serverless Notification API for Your Web Application with Redis
Source: https://upstash.com/docs/redis/tutorials/notification
This tutorial shows how to create a Serverless Notification API for Your Web Application with Redis.
Notifications and announcements help you communicate with your web site
visitors. It is not feasible to update your code and redeploy your website each
time you want to show a new message. It may also be too much investment to set
up a backend and maintain it to just serve these notifications. In this article,
we will build a website which will load the notification message directly from
the Redis database without a backend.
### Backendless? How is that possible?
Yes, we will not use any backend service, even a serverless function. We will
access Redis from the client side directly. This is possible with the read only
REST API provided by Upstash.
### Requirements
* The page will display a notification if the user has not already seen the
notification before.
* The page will only show the latest notification.
Check out
[the code here](https://github.com/upstash/examples/tree/master/examples/serverless-notification-api).
### Project Setup
I will create a React application but you can use any other web framework. It
will simply call the Redis REST API and show the message as a notification.
Create the app:
```shell
npx create-react-app serverless-notification-api
```
Install a toast component to show the notification:
```shell
npm install --save react-toastify
```
Create a free database from [Upstash](https://console.upstash.com/) and copy the
REST url and read only token. You should switch the Read-Only Token setting. In
the database details page, click on the `Read-Only Token` switch.
### Implementation
The logic is simple. We will keep the notifications in a Redis Sorted Set. We
will keep a version (integer) in the local storage. We will use the versions as
scores in the sorted set. Each notification message will have a version (score)
and the higher score means the newer message. At each page load, we will query
the Redis sorted set to load the messages which have higher scores than the
locally stored version. After loading a notification message I will set my local
version equal to the latest notificationās version. This will prevent showing
the same notification to the same users more than once. Here the implementation:
```javascript
import logo from "./logo.svg";
import "./App.css";
import { toast, ToastContainer } from "react-toastify";
import "react-toastify/dist/ReactToastify.css";
import { useEffect } from "react";
function App() {
useEffect(() => {
async function fetchData() {
try {
let version = localStorage.getItem("notification-version");
version = version ? version : 0;
const response = await fetch(
"REPLACE_UPSTASH_REDIS_REST_URL/zrevrangebyscore/messages/+inf/" +
version +
"/WITHSCORES/LIMIT/0/1",
{
headers: {
Authorization: "Bearer REPLACE_UPSTASH_REDIS_REST_TOKEN",
},
}
);
const res = await response.json();
const v = parseInt(res.result[1]);
if (v) {
localStorage.setItem("notification-version", v + 1);
}
toast(res.result[0]);
} catch (e) {
console.error(e);
}
}
fetchData();
});
return (
Edit src/App.js and save to reload.
Learn React
If you are using the Vercel & Upstash integration, you may use the following environment variables:
```shell .env
KV_REST_API_URL=
KV_REST_API_TOKEN=
```
### `4` Define the endpoint
Next, we will define the endpoint which will call Redis:
```javascript title="server/api/increment.ts"
import { defineEventHandler } from "h3";
import { Redis } from "@upstash/redis";
// Initialize Redis
const redis = new Redis({
url: process.env.UPSTASH_REDIS_REST_URL || "",
token: process.env.UPSTASH_REDIS_REST_TOKEN || ""
});
export default defineEventHandler(async () => {
const identifier = "api_call_counter";
try {
// Increment the API call counter and get the updated value
const count = await redis.incr(identifier);
// Optionally, you can also retrieve other information like the last time it was called
const lastCalled = await redis.get("last_called");
const lastCalledAt = lastCalled || "Never";
// Store the current timestamp as the last called time
await redis.set("last_called", new Date().toISOString());
// Return the count and last called time
return {
success: true,
count: count,
lastCalled: lastCalledAt,
};
} catch (error) {
console.error("Redis error:", error);
return {
success: false,
message: "Error interacting with Redis",
};
}
});
```
### `5` Run
Finally, we can run the application and call our endpoint:
```bash
npm run dev
```
If you are using [our example app](https://github.com/upstash/examples/tree/master/examples/nuxt-with-redis),
you can simply click the `Increment` button to run the endpoint we defined.
Otherwise, you can simply make a curl request:
```
curl http://localhost:3000/api/increment
```
When you make the request, you should see something like this:
```
{
"success": true,
"count": 166,
"lastCalled": "2024-10-10T07:04:42.381Z"
}
```
### Notes:
* For best performance the application should run in the same region with the
Redis database's region.
# Redis as a Cache for Your FastAPI App
Source: https://upstash.com/docs/redis/tutorials/python_fastapi_caching
### Introduction
In this tutorial, weāll learn how to use Redis to add caching to a FastAPI application. By caching API responses in Redis, we can reduce database queries, improve response times, and ensure that frequently requested data is delivered quickly.
Weāll create a simple FastAPI app that fetches weather data from an external API. The app will store the results in Redis, so the next time someone requests the same data, it can be returned from the cache instead of making a new API request. Letās get started!
### Environment Setup
First, install FastAPI, the Upstash Redis client, and an ASGI server:
```shell
pip install fastapi upstash-redis uvicorn[standard]
```
### Database Setup
Create a Redis database using the [Upstash Console](https://console.upstash.com) or [Upstash CLI](https://github.com/upstash/cli), and export the `UPSTASH_REDIS_REST_URL` and `UPSTASH_REDIS_REST_TOKEN` to your environment:
```shell
export UPSTASH_REDIS_REST_URL=
export UPSTASH_REDIS_REST_TOKEN=
```
We'll also need to generate a `WEATHER_API_KEY` from [Weather API Website](https://www.weatherapi.com) for free and we will export it.
```shell
export WEATHER_API_KEY=
```
You can also use `python-dotenv` to load environment variables from your `.env` file.
### Application Setup
In this example, we will build an API that fetches weather data and caches it in Redis.
Create `main.py`:
```python main.py
from fastapi import FastAPI
from upstash_redis import Redis
import requests
import os
app = FastAPI()
# Connect to Redis using environment variables
redis = Redis.from_env()
# Mock API endpoint for weather data
WEATHER_API_URL = "https://api.weatherapi.com/v1/current.json"
API_KEY = os.getenv("WEATHER_API_KEY")
@app.get("/weather/{city}")
def get_weather(city: str):
cache_key = f"weather:{city}"
# Check if the data exists in cache
cached_data = redis.get(cache_key)
if cached_data:
return {"source": "cache", "data": cached_data}
# Fetch data from external API
response = requests.get(f"{WEATHER_API_URL}?key={API_KEY}&q={city}")
weather_data = response.json()
# Store the data in Redis cache with a 10-minute expiration
redis.setex(cache_key, 600, weather_data)
return {"source": "api", "data": weather_data}
```
### Running the Application
Run the FastAPI app with Uvicorn:
```shell
uvicorn main:app --reload
```
To test the application you can visit `http://127.0.0.1:8000/weather/istanbul` in your browser or use curl to get the weather data for Istanbul. The first request will fetch the data from the weather API and cache it, and subsequent requests will return the cached data until the cache expires after 10 minutes.
To monitor your data in Redis, you can use the [Upstash Console](https://console.upstash.com) and check out the Data Browser tab.
### Code Breakdown
1. **Redis Setup**: We use `Redis.from_env()` to initialize the Redis connection using the environment variables. Redis will store the weather data with city names as cache keys.
2. **Cache Lookup**: When a request is made to the `/weather/{city}` endpoint, we check if the weather data is already cached by looking up the `weather:{city}` key in Redis. If the data is found in cache, it's returned immediately.
3. **Fetching External Data**: If the data is not in cache, the app sends a request to the external weather API to fetch the latest data. The response is then cached using `redis.setex()`, which stores the data with a 10-minute expiration.
4. **Cache Expiration**: We use a 10-minute TTL (time-to-live) for the cached weather data to ensure it's periodically refreshed. After the TTL expires, the next request will fetch fresh data from the external API and store it in cache again.
# Multithreaded Web Scraping with Redis Caching
Source: https://upstash.com/docs/redis/tutorials/python_multithreading
In this tutorial, weāll build a multithreaded web scraper in Python that leverages Redis for caching responses to minimize redundant HTTP requests. The scraper will be capable of handling groups of URLs across multiple threads while caching responses to reduce load and improve performance.
### Database Setup
Create a Redis database using the [Upstash Console](https://console.upstash.com) or [Upstash CLI](https://github.com/upstash/cli), and add `UPSTASH_REDIS_REST_URL` and `UPSTASH_REDIS_REST_TOKEN` to your `.env` file:
```bash
UPSTASH_REDIS_REST_URL=your_upstash_redis_url
UPSTASH_REDIS_REST_TOKEN=your_upstash_redis_token
```
This file will be used to load environment variables.
### Installation
First, install the necessary libraries using the following command:
```bash
pip install threading requests upstash-redis python-dotenv
```
### Code Explanation
Weāll create a multithreaded web scraper that performs HTTP requests on a set of grouped URLs. Each thread will check if the response for a URL is cached in Redis. If the URL has been previously requested, it will retrieve the cached response; otherwise, it will perform a fresh HTTP request, cache the result, and store it for future requests.
### Code
Hereās the complete code:
```python
import threading
import requests
from upstash_redis import Redis
from dotenv import load_dotenv
# Load environment variables from .env file
load_dotenv()
# Initialize Redis client
redis = Redis.from_env()
# Group URLs by thread, with one or two overlapping URLs across groups
urls_to_scrape_groups = [
[
'https://httpbin.org/delay/1',
'https://httpbin.org/delay/4',
'https://httpbin.org/delay/2',
'https://httpbin.org/delay/5',
'https://httpbin.org/delay/3',
],
[
'https://httpbin.org/delay/5', # Overlapping URL
'https://httpbin.org/delay/6',
'https://httpbin.org/delay/7',
'https://httpbin.org/delay/2', # Overlapping URL
'https://httpbin.org/delay/8',
],
[
'https://httpbin.org/delay/3', # Overlapping URL
'https://httpbin.org/delay/9',
'https://httpbin.org/delay/10',
'https://httpbin.org/delay/4', # Overlapping URL
'https://httpbin.org/delay/11',
],
]
class Scraper(threading.Thread):
def __init__(self, urls):
threading.Thread.__init__(self)
self.urls = urls
self.results = {}
def run(self):
for url in self.urls:
cache_key = f"url:{url}"
# Attempt to retrieve cached response
cached_response = redis.get(cache_key)
if cached_response:
print(f"[CACHE HIT] {self.name} - URL: {url}")
self.results[url] = cached_response
continue # Skip to the next URL if cache is found
# If no cache, perform the HTTP request
print(f"[FETCHING] {self.name} - URL: {url}")
response = requests.get(url)
if response.status_code == 200:
self.results[url] = response.text
# Store the response in Redis cache
redis.set(cache_key, response.text)
else:
print(f"[ERROR] {self.name} - Failed to retrieve {url}")
self.results[url] = None
def main():
threads = []
for urls in urls_to_scrape_groups:
scraper = Scraper(urls)
threads.append(scraper)
scraper.start()
# Wait for all threads to complete
for scraper in threads:
scraper.join()
print("\nScraping results:")
for scraper in threads:
for url, result in scraper.results.items():
print(f"Thread {scraper.name} - URL: {url} - Response Length: {len(result) if result else 'Failed'}")
if __name__ == "__main__":
main()
```
### Explanation
1. **Threaded Scraper Class**: The `Scraper` class is a subclass of `threading.Thread`. Each thread takes a list of URLs and iterates over them to retrieve or fetch their responses.
2. **Redis Caching**:
* Before making an HTTP request, the scraper checks if the response is already in the Redis cache.
* If a cached response is found, it uses that response instead of making a new request, marked with `[CACHE HIT]` in the logs.
* If no cached response exists, it fetches the content from the URL, caches the result in Redis, and proceeds.
3. **Overlapping URLs**:
* Some URLs are intentionally included in multiple groups to demonstrate the cache functionality across threads. Once a URLās response is cached by one thread, another thread retrieving the same URL will pull it from the cache instead of re-fetching.
4. **Main Function**:
* The `main` function initiates and starts multiple `Scraper` threads, each handling a group of URLs.
* It waits for all threads to complete before printing the results.
### Running the Code
Once everything is set up, run the script using:
```bash
python your_script_name.py
```
### Sample Output
You will see output similar to this:
```
[FETCHING] Thread-1 - URL: https://httpbin.org/delay/1
[FETCHING] Thread-1 - URL: https://httpbin.org/delay/4
[CACHE HIT] Thread-2 - URL: https://httpbin.org/delay/5
[FETCHING] Thread-3 - URL: https://httpbin.org/delay/3
...
```
### Benefits of Using Redis Cache
Using Redis as a cache reduces the number of duplicate requests, particularly for overlapping URLs. It allows for quick retrieval of previously fetched responses, enhancing performance and reducing load.
# Rate Limiting for Your FastAPI App
Source: https://upstash.com/docs/redis/tutorials/python_rate_limiting
### Introduction
In this tutorial, weāll learn how to add rate limiting to a FastAPI application using Upstash Redis. Rate limiting is essential for controlling API usage and with Upstash Redis, you can easily implement rate limiting to protect your API resources.
Weāll set up a simple FastAPI app and apply rate limiting to its endpoints. With Upstash Redis, weāll configure a fixed window rate limiter that allows a specific number of requests per given time period.
### Environment Setup
First, install FastAPI, the Upstash Redis client, the Upstash rate limiting package, and an ASGI server:
```shell
pip install fastapi upstash-redis upstash-ratelimit uvicorn[standard]
```
### Database Setup
Create a Redis database using the [Upstash Console](https://console.upstash.com) or [Upstash CLI](https://github.com/upstash/cli), and export the `UPSTASH_REDIS_REST_URL` and `UPSTASH_REDIS_REST_TOKEN` to your environment:
```shell
export UPSTASH_REDIS_REST_URL=
export UPSTASH_REDIS_REST_TOKEN=
```
You can also use `python-dotenv` to load environment variables from your `.env` file.
### Application Setup
In this example, we will build an API endpoint that is rate-limited to a certain number of requests per time window. If the limit is exceeded (e.g., by making more than 10 requests in 10 seconds), the API will return an HTTP 429 error with the message "Rate limit exceeded. Please try again later."
Create `main.py`:
```python main.py
from fastapi import FastAPI, HTTPException
from upstash_ratelimit import Ratelimit, FixedWindow
from upstash_redis import Redis
from dotenv import load_dotenv
import requests
# Load environment variables from .env file
load_dotenv()
# Initialize the FastAPI app
app = FastAPI()
# Initialize Redis client
redis = Redis.from_env()
# Create a rate limiter that allows 10 requests per 10 seconds
ratelimit = Ratelimit(
redis=redis,
limiter=FixedWindow(max_requests=10, window=10), # 10 requests per 10 seconds
prefix="@upstash/ratelimit"
)
@app.get("/expensive_calculation")
def expensive_calculation():
identifier = "api" # Common identifier for rate limiting all users equally
response = ratelimit.limit(identifier)
if not response.allowed:
raise HTTPException(status_code=429, detail="Rate limit exceeded. Please try again later.")
# Placeholder for a resource-intensive operation
result = do_expensive_calculation()
return {"message": "Here is your result", "result": result}
# Simulated function for an expensive calculation
def do_expensive_calculation():
return "Expensive calculation result"
# Test function to check rate limiting
def test_rate_limiting():
url = "http://127.0.0.1:8000/expensive_calculation"
success_count = 0
fail_count = 0
# Attempt 15 requests in quick succession
for i in range(15):
response = requests.get(url)
if response.status_code == 200:
success_count += 1
print(f"Request {i+1}: Success - {response.json()['message']}")
elif response.status_code == 429:
fail_count += 1
print(f"Request {i+1}: Failed - Rate limit exceeded")
# Small delay to avoid flooding
print("\nTest Summary:")
print(f"Total Successful Requests: {success_count}")
print(f"Total Failed Requests due to Rate Limit: {fail_count}")
if __name__ == "__main__":
# Run the FastAPI app in a separate thread or terminal with:
# uvicorn main:app --reload
# To test rate limiting after the server is running
test_rate_limiting()
```
### Running the Application
Run the FastAPI app with Uvicorn:
```shell
uvicorn main:app --reload
```
Run the test function to check the rate limiting:
```shell
python main.py
```
### Testing Rate Limiting
Here's the output you should see when running the test function:
```
Request 1: Success - Here is your result
Request 2: Success - Here is your result
Request 3: Success - Here is your result
Request 4: Success - Here is your result
Request 5: Success - Here is your result
Request 6: Success - Here is your result
Request 7: Success - Here is your result
Request 8: Success - Here is your result
Request 9: Success - Here is your result
Request 10: Success - Here is your result
Request 11: Failed - Rate limit exceeded
Request 12: Failed - Rate limit exceeded
Request 13: Failed - Rate limit exceeded
Request 14: Failed - Rate limit exceeded
Request 15: Failed - Rate limit exceeded
Test Summary:
Total Successful Requests: 10
Total Failed Requests due to Rate Limit: 5
```
### Code Breakdown
1. **Redis and Rate Limiter Setup**:
* We initialize a `Redis` client with `Redis.from_env()` using environment variables for configuration.
* We create a rate limiter using `Ratelimit` with a `FixedWindow` limiter that allows 10 requests per 10 seconds. The `prefix` option is set to organize the Redis keys used by the rate limiter.
2. **Rate Limiting the Endpoint**:
* For the `/expensive_calculation` endpoint, the rate limiter is applied by calling `ratelimit.limit(identifier)`.
* The `identifier` variable uniquely identifies this rate limit. You could use user-specific identifiers (like user IDs) to implement per-user limits.
* If the request exceeds the allowed limit, an HTTP 429 error is returned.
3. **Expensive Calculation Simulation**:
* The `do_expensive_calculation` function simulates a resource-intensive operation. In real scenarios, this could represent database queries, file processing, or other time-consuming tasks.
### Benefits of Rate Limiting with Redis
Using Redis for rate limiting helps control API usage across multiple instances of your app, making it highly scalable. Redisās in-memory storage provides fast access to rate-limiting data, ensuring minimal performance impact on your API.
# Build a Real-Time Chat Application with Serverless Redis
Source: https://upstash.com/docs/redis/tutorials/python_realtime_chat
In this tutorial, we will build a real-time chat application using Flask and SocketIO, leveraging Upstash Redis for efficient message handling. Redis, being a fast, in-memory data store, provides an ideal backbone for real-time messaging systems due to its low latency and support for Pub/Sub messaging patterns.
## Why Upstash Redis?
* **Scalability:** Handles large volumes of messages with minimal latency.
* **Simplicity:** Easy to set up with minimal configuration.
* **Cost-Efficiency:** Serverless model reduces operational costs.
***
## **Setup**
### **1. Install the Required Libraries**
Install Flask, Flask-SocketIO, and the Redis library by running:
```bash
pip install flask flask-socketio redis
```
### **2. Create a Redis Database**
Create a Redis database using the [Upstash Console](https://console.upstash.com) or [Upstash CLI](https://github.com/upstash/cli).
Create a `.env` file in the root of your project with the following content:
```bash
UPSTASH_REDIS_HOST=your_upstash_redis_host
UPSTASH_REDIS_PORT=your_upstash_redis_port
UPSTASH_REDIS_PASSWORD=your_upstash_redis_password
```
## **Code**
Now, it's time to implement the chat application. We'll create a Flask server that uses SocketIO for real-time communication. We'll also configure the server to use Upstash Redis as the message queue.
We need to use the `rediss://` protocol instead of `redis://` to connect to Redis over TLS. This ensures secure communication between the server and the Redis instance.
```python main.py
from flask import Flask, render_template
from flask_socketio import SocketIO
import os
# Initialize Flask app
app = Flask(__name__)
app.config["SECRET_KEY"] = os.getenv("SECRET_KEY", os.urandom(24))
# Set up Redis URL with TLS
redis_password = os.getenv('UPSTASH_REDIS_PASSWORD')
redis_host = os.getenv('UPSTASH_REDIS_HOST')
redis_port = int(os.getenv('UPSTASH_REDIS_PORT', 6379))
redis_url = f"rediss://:{redis_password}@{redis_host}:{redis_port}"
# Initialize SocketIO with Redis message queue
socketio = SocketIO(app, message_queue=redis_url, cors_allowed_origins="*")
# WebSocket handlers
@socketio.on("connect")
def handle_connect():
print("Client connected.")
@socketio.on("disconnect")
def handle_disconnect():
print("Client disconnected.")
@socketio.on("message")
def handle_message(data):
"""Handle incoming chat messages."""
print(f"Message received: {data}")
# Broadcast the message to all connected clients except the sender
socketio.emit("message", data, include_self=False)
# Serve the chat HTML page
@app.route("/")
def index():
return render_template("chat.html") # Render the chat interface template
if __name__ == "__main__":
socketio.run(app, debug=True, host="0.0.0.0", port=8000)
```
### **Code Explanation**
* We initialized a Flask app and set a secret key for session management.
* We set up the Redis URL with TLS for secure communication.
* We initialize a SocketIO instance with the Flask app and configure it to use Redis as the message queue.
* We define WebSocket event handlers for `connect`, `disconnect`, and `message` events.
* The `handle_message` function broadcasts the received message to all connected clients except the sender.
* We define a route to serve the chat interface template.
Now let's create a template for the chat interface. We're not going to go into the details of the HTML and CSS, as the focus is on the real-time messaging functionality.
```html chat.html
Real-Time Chat
```
***
### **Running the Application**
1. Start the server:
```bash
python app.py
```
2. Open your web browser and go to `http://localhost:8000/`.
You should see the chat interface. You can send and recieve messages in real-time. Just open the same URL in multiple tabs or browsers to simulate multiple users chatting with each other.
***
## **Conclusion**
In this tutorial, we built a real-time chat application using Flask, SocketIO, and Upstash Redis. Redis, with its low latency and high throughput, is an ideal choice for real-time messaging systems.
To learn more about Upstash Redis, visit the [Upstash Redis Documentation](https://upstash.com/docs/redis).
# Manage Sessions in Python with Serverless Redis
Source: https://upstash.com/docs/redis/tutorials/python_session
In this tutorial, weāll see how to implement session management in a FastAPI application using Upstash Redis. Weāll use cookies to store session IDs, while session data is maintained in Redis for its speed and expiration features.
## **What Are Sessions and Cookies?**
* **Session:** A session is a mechanism to store user-specific data (like authentication status) between requests. It allows the server to "remember" users as they interact with the application.
* **Cookie:** A small piece of data stored in the clientās browser. In this tutorial, weāll use cookies to store session IDs, which the server uses to fetch session details from Redis.
## **Why Redis?**
Redis is a great choice for session management because:
1. **Fast Lookups:** Redis is an in-memory database, ensuring near-instantaneous access to session data.
2. **Expiration Control:** Built-in expiration functionality allows sessions to automatically expire after a defined timeout.
***
## **Setup**
### **1. Install the Required Libraries**
Install FastAPI, Upstash Redis, and other necessary dependencies:
```bash
pip install fastapi upstash-redis uvicorn python-dotenv
```
### **2. Create a Redis Database**
Create a Redis database using the [Upstash Console](https://console.upstash.com) or [Upstash CLI](https://github.com/upstash/cli).
Create a `.env` file in the root of your project with the following content:
```bash
UPSTASH_REDIS_REST_URL=your_upstash_redis_url
UPSTASH_REDIS_REST_TOKEN=your_upstash_redis_token
```
## **Code**
Let's implement a simple FastAPI application that handles login, profile access, and logout using Redis for session management. We use sliding expiration by updating the session expiration time on every request. If a session is inactive for 15 minutes (900 seconds), it will automatically expire.
```python main.py
from fastapi import FastAPI, Response, Cookie, HTTPException
from pydantic import BaseModel
from upstash_redis import Redis
from dotenv import load_dotenv
import uuid
# Load environment variables
load_dotenv()
redis = Redis.from_env()
app = FastAPI()
SESSION_TIMEOUT_SECONDS = 900 # 15 minutes
# Define the request body model for login
class LoginRequest(BaseModel):
username: str
@app.post("/login/")
async def login(request: LoginRequest, response: Response):
session_id = str(uuid.uuid4())
redis.hset(f"session:{session_id}", values={"user": request.username, "status": "active"})
redis.expire(f"session:{session_id}", SESSION_TIMEOUT_SECONDS)
response.set_cookie(key="session_id", value=session_id, httponly=True)
return {"message": "Logged in successfully", "session_id": session_id}
@app.get("/profile/")
async def get_profile(session_id: str = Cookie(None)):
if not session_id:
raise HTTPException(status_code=403, detail="No session cookie found")
session_data = redis.hgetall(f"session:{session_id}")
if not session_data:
response = Response()
response.delete_cookie(key="session_id") # Clear the expired cookie
raise HTTPException(status_code=404, detail="Session expired")
# Update the session expiration time (sliding expiration)
redis.expire(f"session:{session_id}", SESSION_TIMEOUT_SECONDS)
return {"session_id": session_id, "session_data": session_data}
@app.post("/logout/")
async def logout(response: Response, session_id: str = Cookie(None)):
if session_id:
redis.delete(f"session:{session_id}")
response.delete_cookie(key="session_id")
return {"message": "Logged out successfully"}
```
Let's test the implementation using the following script:
```python test_script.py
import requests
base_url = "http://127.0.0.1:8000"
# Test login
response = requests.post(f"{base_url}/login/", json={"username": "abdullah"})
print("Login Response:", response.json())
# In the browser, you don't need to set cookies manually. The browser will handle it automatically.
session_cookie = response.cookies.get("session_id")
# Test profile
profile_response = requests.get(f"{base_url}/profile/", cookies={"session_id": session_cookie})
print("Access Profile Response:", profile_response.json())
# Test logout
logout_response = requests.post(f"{base_url}/logout/", cookies={"session_id": session_cookie})
print("Logout Response:", logout_response.json())
# Test profile after logout
profile_after_logout_response = requests.get(f"{base_url}/profile/", cookies={"session_id": session_cookie})
print("Access Profile After Logout Response:", profile_after_logout_response.text)
```
***
### **Code Explanation**
1. **`/login/` Endpoint:**
* Generates a unique session ID using `uuid.uuid4()`.
* Stores the session data in Redis using the session ID as the key.
* Sets a cookie named `session_id` with the generated session ID.
* Returns a success message along with the session ID.
2. **`/profile/` Endpoint:**
* Retrieves the session ID from the cookie.
* Fetches the session data from Redis using the session ID.
* Updates the session expiration time.
* Returns the session ID and session data.
3. **`/logout/` Endpoint:**
* Deletes the session data from Redis using the session ID.
* Clears the `session_id` cookie.
***
### **Run the Application**
1. Start the FastAPI server:
```bash
uvicorn main:app --reload
```
2. Run the test script:
```bash
python test_script.py
```
Here's what you should expect:
```plaintext
Login Response: {'message': 'Logged in successfully', 'session_id': '68223c50-ede4-48eb-9d26-4a4dd735c10d'}
Access Profile Response: {'session_id': '68223c50-ede4-48eb-9d26-4a4dd735c10d', 'session_data': {'user': 'abdullah', 'status': 'active'}}
Logout Response: {'message': 'Logged out successfully'}
Access Profile After Logout Response: {"detail":"Session not found or expired"}
```
***
## **Conclusion**
By combining FastAPI, cookies, and Upstash Redis, weāve created a reliable session management system. With Redisās speed and built-in expiration features, this approach ensures secure and efficient handling of user sessions.
To learn more about Upstash Redis, visit the [Upstash Redis Documentation](https://upstash.com/docs/redis).
# Building a URL Shortener with Redis
Source: https://upstash.com/docs/redis/tutorials/python_url_shortener
### Introduction
In this tutorial, weāll build a simple URL shortener using Redis and Python. The short URL service will generate a random short code for each URL, store it in Redis, and allow users to retrieve the original URL using the short code. Weāll also implement an expiration time for each shortened URL, making it expire after a specified period.
### Environment Setup
First, install the necessary dependencies, including Upstash Redis and `python-dotenv` for environment variables:
```shell
pip install upstash-redis
```
### Database Setup
Create a Redis database using the [Upstash Console](https://console.upstash.com) or [Upstash CLI](https://github.com/upstash/cli), and export the `UPSTASH_REDIS_REST_URL` and `UPSTASH_REST_TOKEN` to your environment:
```shell
export UPSTASH_REDIS_REST_URL=
export UPSTASH_REDIS_REST_TOKEN=
```
You can also use `python-dotenv` to load environment variables from a `.env` file:
```text .env
UPSTASH_REDIS_REST_URL=
UPSTASH_REDIS_REST_TOKEN=
```
### Application Setup
In this example, we will build a URL shortener where each short URL will be stored in Redis with an expiration time.
Create `url_shortener.py`:
```py url_shortener.py
import string
import random
from upstash_redis import Redis
from dotenv import load_dotenv
import os
# Load environment variables
load_dotenv()
# Redis connection
redis = Redis.from_env()
# Characters to generate the short URL from
CHARS = string.ascii_letters + string.digits
BASE_URL = "https://short.url/"
# Function to generate a random string for the short URL
def generate_short_code(length=6):
return ''.join(random.choices(CHARS, k=length))
# Function to shorten the URL with an expiration time
def shorten_url(url, expiration=3600):
# Generate a random short code
short_code = generate_short_code()
# Save the short code in Redis
redis.set(short_code, url, ex=expiration)
return BASE_URL + short_code
# Function to get the original URL from the short URL
def get_original_url(short_code):
return redis.get(short_code)
# Example usage
if __name__ == "__main__":
original_url = "https://example.com/my-very-long-url"
# Shorten the URL
short_url = shorten_url(original_url, expiration=600)
print(f"Shortened URL: {short_url}")
# Get the original URL
original_url = get_original_url(short_url.split("/")[-1])
if original_url:
print(f"Original URL: {original_url}")
else:
print("Short URL expired or not found")
```
### Running the Application
Simply run the Python script:
```shell
python url_shortener.py
```
This script will shorten a long URL, store the mapping in Redis, and print the shortened URL. It will then attempt to retrieve the original URL using the short code.
Here is an example output:
```shell
Shortened URL: https://short.url/0lSLFI
Original URL: https://example.com/my-very-long-url
```
To monitor your data in Redis, you can use the [Upstash Console](https://console.upstash.com) and check out the Data Browser tab.
### How to Use the URL Shortener for Web Applications
1. Extract the short code from the shortened URL (e.g., `0lSLFI`).
2. Look up the original URL in Redis using that code.
3. Redirect the user to the original URL.
### Code Breakdown
1. **Random Short Code Generation**: The `generate_short_code` function creates a random string of characters (letters and digits) that will serve as the short code for the URL.
2. **Storing in Redis**: The `shorten_url` function takes the original URL and stores it in Redis using the randomly generated short code as the key. The `ex` parameter sets an expiration time (in seconds) for how long the shortened URL will be valid.
3. **Retrieving the Original URL**: The `get_original_url` function takes the short code and looks it up in Redis to retrieve the original URL. If the short code doesn't exist (due to expiration or other reasons), it returns `None`.
4. **Expiration Handling**: If the short code has expired, Redis automatically removes the entry, and the script will print a message indicating that the URL has expired or cannot be found.
# Serverless Python API with Redis
Source: https://upstash.com/docs/redis/tutorials/pythonapi
You can find the project source code on GitHub.
This tutorial shows how to build a serverless API for Page View Counter with
Python and Redis. The API will the count page views and show it in JSON format.
### Prerequisites
* Complete all steps in [Getting started with the AWS CDK](https://docs.aws.amazon.com/cdk/v2/guide/getting_started.html)
### Project Setup
Create and navigate to a directory named `counter-cdk`. CDK CLI uses this directory name to name things in your CDK code, so if you decide to use a different name, don't forget to make the appropriate changes when applying this tutorial.
```shell
mkdir counter-cdk && cd counter-cdk
```
Initialize a new CDK project.
```shell
cdk init app --language typescript
```
### Counter Function Setup
Create a folder named `api` under `lib`
```shell
mkdir lib/api
```
Create `/lib/api/requirements.txt`
```txt /lib/api/requirements.txt
upstash-redis
```
Create `/lib/api/index.py`
```py /lib/api/index.py
from upstash_redis import Redis
redis = Redis.from_env()
def handler(event, context):
count = redis.incr('counter')
return {
'statusCode': 200,
'body': f'Counter: {count}'
}
```
### Counter Stack Setup
Update `/lib/counter-cdk-stack.ts`
```ts /lib/counter-cdk-stack.ts
import * as cdk from 'aws-cdk-lib';
import { Construct } from 'constructs';
import * as lambda from 'aws-cdk-lib/aws-lambda';
import * as path from 'path';
export class CounterCdkStack extends cdk.Stack {
constructor(scope: Construct, id: string, props?: cdk.StackProps) {
super(scope, id, props);
const counterFunction = new lambda.Function(this, 'CounterFunction', {
code: lambda.Code.fromAsset(path.join(__dirname, 'api'), {
bundling: {
image: lambda.Runtime.PYTHON_3_9.bundlingImage,
command: [
'bash', '-c',
'pip install -r requirements.txt -t /asset-output && cp -au . /asset-output'
],
},
}),
runtime: lambda.Runtime.PYTHON_3_9,
handler: 'index.handler',
environment: {
UPSTASH_REDIS_REST_URL: process.env.UPSTASH_REDIS_REST_URL || '',
UPSTASH_REDIS_REST_TOKEN: process.env.UPSTASH_REDIS_REST_TOKEN || '',
},
});
const counterFunctionUrl = counterFunction.addFunctionUrl({
authType: lambda.FunctionUrlAuthType.NONE,
});
new cdk.CfnOutput(this, "counterFunctionUrlOutput", {
value: counterFunctionUrl.url,
})
}
}
```
### Database Setup
Create a Redis database using [Upstash Console](https://console.upstash.com) or [Upstash CLI](https://github.com/upstash/cli) and export `UPSTASH_REDIS_REST_URL` and `UPSTASH_REDIS_REST_TOKEN` to your environment.
```shell
export UPSTASH_REDIS_REST_URL=
export UPSTASH_REDIS_REST_TOKEN=
```
### Deploy
Run in the top folder:
```shell
cdk synth
cdk bootstrap
cdk deploy
```
Visit the output url.
# AWS Lambda Rate Limiting with Serverless Redis
Source: https://upstash.com/docs/redis/tutorials/rate-limiting
In this tutorial, we will deploy a AWS Lambda function ratelimited based on the client's IP address using `@upstash/ratelimit` and Serverless Framework.
### Prerequisites
1. Install the Serverless Framework with `npm i serverless -g`
### Project Setup
Create a Serverless Framework application with the following options:
```shell
ā tutorials > ā serverless
Serverless Ļ Framework
Welcome to Serverless Framework V.4
Create a new project by selecting a Template to generate scaffolding for a specific use-case.
ā Select A Template: Ā· AWS / Node.js / HTTP API
ā Name Your Project: Ā· ratelimit-serverless
ā Template Downloaded
ā Create Or Select An Existing App: Ā· Create A New App
ā Name Your New App: Ā· ratelimit-serverless
Your new Service "ratelimit-serverless" is ready. Here are next steps:
ā¢ Open Service Directory: cd ratelimit-serverless
ā¢ Install Dependencies: npm install (or use another package manager)
ā¢ Deploy Your Service: serverless deploy
```
```shell
cd ratelimit-serverless
```
Create `package.json` with `@upstash/ratelimit` as a dependency:
```json package.json
{
"dependencies": {
"@upstash/ratelimit": "latest",
"@upstash/redis": "latest"
}
}
```
Install the dependencies:
```shell
npm install
```
### Database Setup
Create a Redis database using [Upstash Console](https://console.upstash.com) or [Upstash CLI](https://github.com/upstash/cli) and copy the `UPSTASH_REDIS_REST_URL` and `UPSTASH_REDIS_REST_TOKEN` into your `.env` file.
```shell .env
UPSTASH_REDIS_REST_URL=
UPSTASH_REDIS_REST_TOKEN=
```
### Ratelimited Function Setup
Update `handler.js`:
```js handler.js
const { Ratelimit } = require("@upstash/ratelimit");
const { Redis } = require("@upstash/redis");
const ratelimit = new Ratelimit({
redis: Redis.fromEnv(),
limiter: Ratelimit.slidingWindow(10, "10 s"),
prefix: "@upstash/ratelimit",
analytics: true,
});
exports.ratelimit = async (event) => {
const identifier = event.requestContext.http.sourceIP;
const { success, limit, remaining, pending } = await ratelimit.limit(
identifier
);
const response = {
success: success,
limit: limit,
remaining: remaining,
};
// pending is a promise for handling the analytics submission
await pending;
if (!success) {
return {
statusCode: 429,
body: JSON.stringify(response),
};
}
return {
statusCode: 200,
body: JSON.stringify(response),
};
};
```
Update `serverless.yml` to pass the environment variables:
```yaml serverless.yml
service: ratelimit-serverless
provider:
name: aws
runtime: nodejs20.x
environment:
UPSTASH_REDIS_REST_URL: ${env:UPSTASH_REDIS_REST_URL}
UPSTASH_REDIS_REST_TOKEN: ${env:UPSTASH_REDIS_REST_TOKEN}
functions:
ratelimit:
handler: handler.ratelimit
events:
- httpApi:
path: /
method: get
```
### Developing
Run the following command to start your dev session.
```shell
serverless dev
```
### Deployment
Run the following command to deploy your service.
```shell
serverless deploy
```
Visit the output url.
# Serverless Redisson
Source: https://upstash.com/docs/redis/tutorials/redisson
This tutorial shows how to use Upstash with Redisson client.
This tutorial shows how to use Upstash with Redisson client.
See [code](https://github.com/upstash/examples/tree/master/examples/redisson)
### `1` Create a Maven Project
Create a maven project and copy the following dependency to your pom.xml
```xml
org.redisson
redisson
3.15.4
```
### `2` Create a Redis (Upstash) Database
Create a database as [getting started](../overall/getstarted)
### `3` Code
Create your java file and replace Redis password and URL below. If you enabled
TLS, the endpoint should start with `rediss`
```typescript
public class Main {
public static void main(String[] args) {
Config config = new Config();
config.useSingleServer().setPassword("YOUR_PASSWORD")
// use "rediss://" for SSL connection
.setAddress("YOUR_ENDPOINT");
RedissonClient redisson = Redisson.create(config);
RMap map = redisson.getMap("map");
map.put("foo", "bar");
System.out.println(map.get("foo"));
}
}
```
# Roadmap Voting App with Serverless Redis
Source: https://upstash.com/docs/redis/tutorials/roadmapvotingapp
This is a single page application powered by upstash and next.js.
We have developed an advanced version of Roadmap Voting App where users should
log in to request or vote for a new feature. See it live version in [Upstash
Roadmap](https://roadmap.upstash.com). See [the blog
post](https://blog.upstash.com/roadmap-application) to learn about it. The
below example allows users to request features anonymously.
In this tutorial we will write a single page application which uses Redis as
state store in a Next.js application.
The example is a basic roadmap voting application where users enter and vote for
feature requests. You can check the complete application in
[Upstash Roadmap page](https://roadmap.upstash.com)
### Deploy Yourself
You can check the source code of the complete application
[here](https://github.com/upstash/serverless-examples/tree/master/roadmap-voting-app).
Thanks to [Upstash\&Vercel integration](https://vercel.com/integrations/upstash),
you can deploy the application yourself with zero cost/code by clicking below:
[](https://vercel.com/new/git/external?repository-url=https%3A%2F%2Fgithub.com%2Fupstash%2Fserverless-tutorials%2Ftree%2Fmaster%2Froadmap-voting-app\&env=LOGO\&envDescription=Enter%20URL%20for%20your%20project%2Fcompany%20logo\&envLink=https%3A%2F%2Fdocs.upstash.com%2Fdocs%2Ftutorials%2Froadmap_voting_app\&project-name=roadmap-voting\&repo-name=roadmap-voting\&demo-title=Roadmap%20Voting\&demo-description=Roadmap%20Voting%20Page%20for%20Your%20Project\&demo-url=https%3A%2F%2Froadmap.upstash.com\&integration-ids=oac_V3R1GIpkoJorr6fqyiwdhl17)
### Create Next.js Project
We will use Next.js as web framework. So let's create a next.js app and install
the redis client first.
`npx create-next-app nextjs-with-redis`
`npm install ioredis`
### index.js
Our application will be a single page. We will list the features with their
order of votes. There will be 3 actions available for the page user:
* The user will suggest a new feature.
* The user will vote up an existing feature.
* The user will enter their email to be notified of a release of any feature.
The below are the parts that handles all those. If you want to check the full
page see
[here](https://github.com/upstash/serverless-tutorials/blob/master/roadmap-voting-app/pages/index.js)
```javascript
import Head from 'next/head'
import { ToastContainer, toast } from 'react-toastify';
import * as React from "react";
class Home extends React.Component {
...
refreshData() {
fetch("api/list")
.then(res => res.json())
.then(
(result) => {
this.setState({
isLoaded: true,
items: result.body
});
this.inputNewFeature.current.value = "";
},
(error) => {
this.setState({
isLoaded: true,
error
});
}
)
}
vote(event, title) {
const requestOptions = {
method: 'POST',
headers: {'Content-Type': 'application/json'},
body: JSON.stringify({"title": title})
};
console.log(requestOptions);
fetch('api/vote', requestOptions)
.then(response => response.json()).then(data => {
console.log(data)
if(data.error) {
toast.error(data.error, {hideProgressBar: true, autoClose: 3000});
} else {
this.refreshData()
}
})
}
handleNewFeature(event) {
const requestOptions = {
method: 'POST',
headers: {'Content-Type': 'application/json'},
body: JSON.stringify({"title": this.inputNewFeature.current.value})
};
fetch('api/create', requestOptions)
.then(response => response.json()).then(data => {
if(data.error) {
toast.error(data.error, {hideProgressBar: true, autoClose: 5000});
} else {
toast.info("Your feature has been added to the list.", {hideProgressBar: true, autoClose: 3000});
this.refreshData()
}
});
event.preventDefault();
}
handleNewEmail(event) {
const requestOptions = {
method: 'POST',
headers: {'Content-Type': 'application/json'},
body: JSON.stringify({"email": this.inputEmail.current.value})
};
console.log(requestOptions);
fetch('api/addemail', requestOptions)
.then(response => response.json()).then(data => {
if(data.error) {
toast.error(data.error, {hideProgressBar: true, autoClose: 3000});
} else {
toast.info("Your email has been added to the list.", {hideProgressBar: true, autoClose: 3000});
this.refreshData()
}
});
event.preventDefault();
}
}
export default Home;
```
### APIs
With Next.js, you can write server-side APIs within your project. We will have 4
apis:
* list features
* vote a feature
* add a new feature
* add email
Now let's examine these API implementations:
#### list.js
The list API connects to the Redis and fetches feature requests ordered by their
scores (votes) from the Sorted Set `roadmap`.
redis.clients
jedis
3.6.0
...
```
Update `serverless.yml` as below:
```yaml serverless.yml
service: counter-api
frameworkVersion: '3'
provider:
name: aws
runtime: java17
package:
artifact: target/hello-dev.jar
functions:
hello:
handler: com.serverless.Handler
events:
- httpApi:
path: /hello
method: get
```
### Counter Function Setup
Update `src/main/java/com/serverless/Handler.java` as below:
```java src/main/java/com/serverless/Handler.java
package com.serverless;
import java.util.Map;
import com.amazonaws.services.lambda.runtime.Context;
import com.amazonaws.services.lambda.runtime.RequestHandler;
import redis.clients.jedis.Jedis;
public class Handler implements RequestHandler, ApiGatewayResponse> {
@Override
public ApiGatewayResponse handleRequest(Map input, Context context) {
Jedis jedis = new Jedis("lasting-roughy-29092.upstash.io", 6379, true);
jedis.auth("********");
Long value = jedis.incr("counter");
jedis.close();
String message = "Hello World, Count:" + value;
return ApiGatewayResponse.builder()
.setStatusCode(200)
.setObjectBody(message)
.build();
}
}
```
In the above code, you need to replace your Redis endpoint and password. You can copy Jedis connection code from the [Upstash Redis Console](https://console.upstash.com/redis) -> Your Database -> Connect to your database -> Java.
### Build and Deploy
Build your project:
```shell
mvn clean install
```
Deploy to AWS:
```shell
serverless deploy
```
Visit the output URL to see the counter in action.
# Using AWS SAM
Source: https://upstash.com/docs/redis/tutorials/using_aws_sam
You can find the project source code on GitHub.
This tutorial implements a serverless application and deploy it to AWS Lambda
using AWS SAM.
### Prerequisites
1. [Complete AWS SAM Prerequisites](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/prerequisites.html)
2. [Install the AWS SAM CLI](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/install-sam-cli.html)
### Project Setup
Create a SAM application with the following options:
```shell
ā tutorials > ā sam init
Which template source would you like to use?
1 - AWS Quick Start Templates
2 - Custom Template Location
Choice: 1
Choose an AWS Quick Start application template
1 - Hello World Example
2 - Data processing
3 - Hello World Example with Powertools for AWS Lambda
4 - Multi-step workflow
5 - Scheduled task
6 - Standalone function
7 - Serverless API
8 - Infrastructure event management
9 - Lambda Response Streaming
10 - Serverless Connector Hello World Example
11 - Multi-step workflow with Connectors
12 - GraphQLApi Hello World Example
13 - Full Stack
14 - Lambda EFS example
15 - DynamoDB Example
16 - Machine Learning
Template: 1
Use the most popular runtime and package type? (Python and zip) [y/N]: y
Would you like to enable X-Ray tracing on the function(s) in your application? [y/N]: N
Would you like to enable monitoring using CloudWatch Application Insights?
For more info, please view https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/cloudwatch-application-insights.html [y/N]: N
Would you like to set Structured Logging in JSON format on your Lambda functions? [y/N]: N
```
```shell
cd sam-app
```
### Counter Function Setup
Update `/hello_world/requirements.txt` to include `upstash-redis`:
```txt /hello_world/requirements.txt
requests
upstash-redis
```
Update `/hello_world/app.py`:
```python /hello_world/app.py
from upstash_redis import Redis
redis = Redis.from_env()
def lambda_handler(event, context):
count = redis.incr('counter')
return {
'statusCode': 200,
'body': f'Counter: {count}'
}
```
Update `/template.yaml` to pass Upstash Redis environment variables:
```yaml /template.yaml
AWSTemplateFormatVersion: '2010-09-09'
Transform: AWS::Serverless-2016-10-31
Description: >
sam-app
Sample SAM Template for sam-app
Globals:
Function:
Timeout: 3
MemorySize: 128
Parameters:
UpstashRedisRestURL:
Type: String
UpstashRedisRestToken:
Type: String
Resources:
HelloWorldFunction:
Type: AWS::Serverless::Function
Properties:
CodeUri: hello_world/
Handler: app.lambda_handler
Runtime: python3.9
Architectures:
- x86_64
Events:
HelloWorld:
Type: Api
Properties:
Path: /hello
Method: get
Environment:
Variables:
UPSTASH_REDIS_REST_URL: !Ref UpstashRedisRestURL
UPSTASH_REDIS_REST_TOKEN: !Ref UpstashRedisRestToken
Outputs:
HelloWorldApi:
Description: "API Gateway endpoint URL for Prod stage for Hello World function"
Value: !Sub "https://${ServerlessRestApi}.execute-api.${AWS::Region}.amazonaws.com/Prod/hello/"
HelloWorldFunction:
Description: "Hello World Lambda Function ARN"
Value: !GetAtt HelloWorldFunction.Arn
HelloWorldFunctionIamRole:
Description: "Implicit IAM Role created for Hello World function"
Value: !GetAtt HelloWorldFunctionRole.Arn
```
### Database Setup
Create a Redis database using [Upstash Console](https://console.upstash.com) or [Upstash CLI](https://github.com/upstash/cli). Copy `UPSTASH_REDIS_REST_URL` and `UPSTASH_REDIS_REST_TOKEN` for the next steps.
### Build
```shell
sam build
```
### Deploy
Enter your database related environment variables when prompted.
```shell
sam deploy --guided
```
Visit the HelloWorld API Gateway URL to see the response.
# Serverless Redis on Google Cloud Functions
Source: https://upstash.com/docs/redis/tutorials/using_google_cloud_functions
You can find the project source code on GitHub.
Google Cloud Functions is the second most popular serverless execution platform.
Similar to AWS Lambda it is stateless, namely you need to access external
resources to read or write your applications state. In this post, we will
introduce Redis as a database for your Google Cloud functions.
This tutorial shows how to build a serverless API with Redis on Google Cloud
Functions. The API will simply count the views and show it in JSON format.
### Prerequisites
1. [Create a Google Cloud Project.](https://cloud.google.com/resource-manager/docs/creating-managing-projects)
2. [Enable billing for your project.](https://cloud.google.com/billing/docs/how-to/verify-billing-enabled#console)
3. Enable Cloud Functions, Cloud Build, Artifact Registry, Cloud Run, Logging, and Pub/Sub APIs.
### Database Setup
Create a Redis database using [Upstash Console](https://console.upstash.com) or [Upstash CLI](https://github.com/upstash/cli). Copy `UPSTASH_REDIS_REST_URL` and `UPSTASH_REDIS_REST_TOKEN` for the next steps.
### Counter Function Setup & Deploy
1. Go to [Cloud Functions](https://console.cloud.google.com/functions/list) in Google Cloud Console.
2. Click **Create Function**.
3. Setup **Basics and Trigger** Configuration like below:
4. Using your `UPSTASH_REDIS_REST_URL` and `UPSTASH_REDIS_REST_TOKEN`, setup **Runtime environment variables** under **Runtime, build, connections and privacy settings** like below.
5. Click **Next**.
6. Set **Entry point** to `counter`.
7. Update `index.js`
```js index.js
const { Redis } = require("@upstash/redis");
const functions = require('@google-cloud/functions-framework');
const redis = new Redis({
url: process.env.UPSTASH_REDIS_REST_URL,
token: process.env.UPSTASH_REDIS_REST_TOKEN
});
functions.http('counter', async (req, res) => {
const count = await redis.incr("counter");
res.send("Counter:" + count);
});
```
8. Update `package.json` to include `@upstash/redis`.
```json package.json
{
"dependencies": {
"@google-cloud/functions-framework": "^3.0.0",
"@upstash/redis": "^1.31.6"
}
}
```
9. Click **Deploy**.
10. Visit the given URL.
# Using Serverless Framework
Source: https://upstash.com/docs/redis/tutorials/using_serverless_framework
You can find the project source code on GitHub.
This tutorial implements a serverless application and deploys it to AWS Lambda
using Serverless Framework
### Prerequisites
1. Install the Serverless Framework with `npm i serverless -g`
### Project Setup
Create a Serverless Framework application with the following options:
```shell
ā tutorials > ā serverless
Serverless Ļ Framework
Welcome to Serverless Framework V.4
Create a new project by selecting a Template to generate scaffolding for a specific use-case.
ā Select A Template: Ā· AWS / Node.js / HTTP API
ā Name Your Project: Ā· counter-serverless
ā Template Downloaded
ā Create Or Select An Existing App: Ā· Create A New App
ā Name Your New App: Ā· counter-serverless
Your new Service "counter-serverless" is ready. Here are next steps:
ā¢ Open Service Directory: cd counter-serverless
ā¢ Install Dependencies: npm install (or use another package manager)
ā¢ Deploy Your Service: serverless deploy
```
```shell
cd counter-serverless
```
Create `package.json` with `@upstash/redis` as a dependency:
```json package.json
{
"dependencies": {
"@upstash/redis": "latest"
}
}
```
Install the dependencies:
```shell
npm install
```
### Database Setup
Create a Redis database using [Upstash Console](https://console.upstash.com) or [Upstash CLI](https://github.com/upstash/cli) and copy the `UPSTASH_REDIS_REST_URL` and `UPSTASH_REDIS_REST_TOKEN` into your `.env` file.
```shell .env
UPSTASH_REDIS_REST_URL=
UPSTASH_REDIS_REST_TOKEN=
```
### Counter Function Setup
Update `handler.js`:
```js handler.js
const { Redis } = require('@upstash/redis');
const redis = Redis.fromEnv();
exports.counter = async (event) => {
const count = await redis.incr("counter");
return {
statusCode: 200,
body: JSON.stringify('Counter: ' + count),
};
};
```
Update `serverless.yml` to pass the environment variables:
```yaml serverless.yml
service: counter-serverless
provider:
name: aws
runtime: nodejs20.x
environment:
UPSTASH_REDIS_REST_URL: ${env:UPSTASH_REDIS_REST_URL}
UPSTASH_REDIS_REST_TOKEN: ${env:UPSTASH_REDIS_REST_TOKEN}
functions:
counter:
handler: handler.counter
events:
- httpApi:
path: /
method: get
```
### Developing
Run the following command to start your dev session.
```shell
serverless dev
```
### Deployment
Run the following command to deploy your service.
```shell
serverless deploy
```
Visit the output url.
# Algorithm
Source: https://upstash.com/docs/search/features/algorithm
Upstash Search combines semantic search with traditional full-text search
for accurate and relevant results. What way, Upstash Search captures what users mean (also known as [search intent](https://backlinko.com/hub/seo/search-intent)), while still matching important keywords.
Together, both approaches let Upstash Search:
* Understand what users are trying to find, even if they don't word it perfectly
* Find documents with related or alternative phrasing
* Work across all kinds of content and domains
Behind the scenes, user queries get a subtle boost from large language models,
helping the system better understand context and return smarter results
even when queries are vague or incomplete.
# Content and Metadata
Source: https://upstash.com/docs/search/features/content-and-metadata
How to use content and metadata fields in your documents
***
## Content
The `content` field contains the searchable data of your documents. This is what gets indexed and can be queried.
* **Required**: You must provide `content` when upserting documents
* **Format**: JSON object structure
* **Searchable**: All fields within content are indexed for search
* **Filterable**: Content fields can be used in filter queries
```py
index.upsert(
documents=[
{
"id": "star-wars",
"content": { "text": "Star Wars is a sci-fi space opera."}
}
]
)
```
```ts
await index.upsert([
{
id: "star-wars",
content: { title: "Star Wars", genre: "sci-fi", category: "classic" }
}
]);
```
***
## Metadata
The `metadata` field stores additional context about your documents that won't be indexed for search. This is useful for data you want to retrieve with your search results but don't need to search through.
* **Optional**: You can upsert documents without metadata
* **Format**: JSON object structure
* **Not Searchable**: Metadata fields are not indexed
```py
index.upsert(
documents=[
{
"id": "star-wars",
"content": { "text": "Star Wars is a sci-fi space opera."},
"metadata": {
"genre": "sci-fi",
}
}
]
)
```
```ts
await index.upsert([
{
id: "star-wars",
content: { title: "Star Wars", genre: "sci-fi", category: "classic" },
metadata: { director: "George Lucas" } ,
}
]);
```
***
## Best Practices
| Use Content When | Use Metadata When |
| ----------------------------------------------------- | ---------------------------------------------------- |
| Users need to search for this information | Information is for display/reference only (e.g. IDs) |
| The field is important for finding relevant documents | The field provides context after finding documents |
| You want to filter results by this field | You need to track internal system information |
***
## Examples & Common Patterns
1. E-commerce Products
```javascript
{
// š searchable and filterable
content: {
name: "Wireless Headphones",
description: "Noise-cancelling bluetooth headphones",
brand: "Sony",
category: "Electronics"
},
// š not searchable, for reference only
metadata: {
sku: "AT-WH-001",
warehouse_location: "A3-15",
supplier_id: "SUP-123"
}
}
```
2. Knowledge Base Articles
```javascript
{
// š searchable and filterable
content: {
title: "How to Reset Your Password",
body: "Follow these steps to reset your password...",
tags: ["password", "security", "account"]
},
// š not searchable, for reference only
metadata: {
author_id: "usr_123",
version: 3,
approved_by: "usr_456",
view_count: 1523
}
}
```
3. News Articles
```javascript
{
// š searchable and filterable
content: {
headline: "Tech Company Announces New Product",
excerpt: "In a press conference today...",
category: "Technology",
keywords: ["innovation", "product launch"]
},
// š not searchable, for reference only
metadata: {
source_url: "https://news.example.com/article/123",
syndication_rights: true,
word_count: 200
}
}
```
# Filtering
Source: https://upstash.com/docs/search/features/filtering
Search queries with filters only return documents which have the content matching with the filter.
Upstash Search allows you to filter by content keys which have the following value types:
* string
* number
* boolean
* object
* array
Filtering is implemented as a combination of in and post-filtering. Every query is assigned a filtering budget,
determining the number of candidate documents that can be compared against the filter during query execution. If this
budget is exceeded, the system fallbacks into post-filtering. Therefore, with highly selective filters, fewer
than `topK` documents may be returned.
***
## Filter Syntax
A filter has a syntax that resembles SQL, which consists of operators on content keys and boolean operators
to combine them.
Assuming you have content like below:
```typescript
{
// š searchable and filterable
content: {
name: "Wireless Headphones",
description: "Noise-cancelling bluetooth headphones",
brand: "Sony",
category: "Electronics",
warehouse_location: "A3-15",
in_stock: 3
},
// š not searchable, for reference only
metadata: {
sku: "AT-WH-001",
supplier_id: "SUP-123",
}
}
```
Filter documents like so:
```python
scores = index.search(
query="sony headphones",
filter="warehouse_location = 'A3-15'",
)
```
```ts
const searchResults = await index.search({
query: "sony headphones",
filter: "warehouse_location = 'A3-15'",
});
```
***
### Operators
#### Equals (=)
The `equals` operator filters content whose values are equal to the given literal.
It is applicable to *string*, *number*, and *boolean* values.
```SQL
warehouse_location = 'A3-15' AND in_stock = 3
```
***
#### Not Equals (!=)
The `not equals` operator filters content whose values are not equal to the given literal.
It is applicable to *string*, *number*, and *boolean* values.
```SQL
warehouse_location != 'A3-15' AND in_stock != 3
```
***
#### Less Than (\<)
The `less than` operator filters content whose values are less than the given literal.
It is applicable to *number* values.
```SQL
in_stock < 3
```
***
#### Less Than or Equals (\<=)
The `less than or equals` operator filters content whose values are less than or equal to the given literal.
It is applicable to *number* values.
```SQL
in_stock <= 3
```
***
#### Greater Than (>)
The `greater than` operator filters content whose values are greater than the given literal.
It is applicable to *number* values.
```SQL
in_stock > 3
```
***
#### Greater Than or Equals (>=)
The `greater than or equals` operator filters content whose values are greater than or equal to the given literal.
It is applicable to *number* values.
```SQL
in_stock >= 3
```
***
#### Glob
The `glob` operator filters content whose values match with the given UNIX glob pattern.
It is applicable to *string* values.
It is a case sensitive operator.
The glob operator supports the following wildcards:
* `*` matches zero or more characters.
* `?` matches exactly one character.
* `[]` matches one character from the list
* `[abc]` matches either `a`, `b`, or `c`.
* `[a-z]` matches one of the range of characters from `a` to `z`.
* `[^abc]` matches any one character other than `a`, `b`, or `c`.
* `[^a-z]` matches any one character other than `a` to `z`.
For example, the filter below would only match with warehouse locations whose first character is `A` or `B`.
```SQL
warehouse_location GLOB '[AB]*'
```
***
#### Not Glob
The `not glob` operator filters content whose values do not match with the given UNIX glob pattern.
It is applicable to *string* values.
It has the same properties with the glob operator.
For example, the filter below would only match with warehouse locations whose first character is anything other than `A`.
```SQL
warehouse_location NOT GLOB 'A*'
```
***
#### In
The `in` operator filters content whose values are equal to any of the given literals.
It is applicable to *string*, *number*, and *boolean* values.
```SQL
country IN ('Germany', 'Turkey', 'France')
```
Semantically, it is equivalent to equals operator applied to all of the given literals with `OR` boolean operator in between:
```SQL
country = 'Germany' OR country = 'Turkey' OR country = 'France'
```
***
#### Not In
The `not in` operator filters content whose values are not equal to any of the given literals.
It is applicable to *string*, *number*, and *boolean* values.
```SQL
economy.currency NOT IN ('USD', 'EUR')
```
Semantically, it is equivalent to not equals operator applied to all of the given literals with `AND` boolean operator in between:
```SQL
economy.currency != 'USD' AND economy.currency != 'EUR'
```
***
#### Contains
The `contains` operator filters content whose values contain the given literal.
It is applicable to *array* values.
```SQL
economy.major_industries CONTAINS 'Tourism'
```
***
#### Not Contains
The `not contains` operator filters content whose values do not contain the given literal.
It is applicable to *array* values.
```SQL
economy.major_industries NOT CONTAINS 'Steel Production'
```
***
#### Has Field
The `has field` operator filters content which have the given JSON field.
```SQL
HAS FIELD geography.coordinates
```
***
#### Has Not Field
The `has not field` operator filters content which do not have the given JSON field.
```SQL
HAS NOT FIELD geography.coordinates.longitude
```
***
### Boolean Operators
Operators above can be combined with `AND` and `OR` boolean operators to form
compound filters.
```SQL
country = 'Turkey' AND population > 10000000
```
Boolean operators can be grouped with parentheses to have higher precedence.
```SQL
country = 'Turkey' AND (population > 10000000 OR is_capital = false)
```
When no parentheses are provided in ambiguous filters, `AND` will have higher
precedence than `OR`. So, the filter
```SQL
country = 'Turkey' AND population > 10000000 OR is_capital = false
```
would be equivalent to
```SQL
(country = 'Turkey' AND population > 10000000) OR is_capital = false
```
***
### Filtering Nested Objects
It is possible to filter nested object fields by referencing them with the `.` accessor.
Nested fields can be at arbitrary depths, so more than one `.` accessor can be used
in the same identifier.
```SQL
economy.currency != 'USD' AND geography.coordinates.latitude >= 35.0
```
***
### Filtering Array Elements
Apart from the `CONTAINS` and `NOT CONTAINS` operators, individual array elements can also
be filtered by referencing them with the `[]` accessor by their indexes.
Indexing is zero based.
```SQL
economy.major_industries[0] = 'Tourism'
```
Also, it is possible to index from the back using the `#` character with negative values.
`#` can be thought as the number of elements in the array, so `[#-1]` would reference the
last element.
```SQL
economy.major_industries[#-1] = 'Finance'
```
***
### Miscellaneous
* Identifiers (the left side of the operators) should be of the form `[a-zA-Z_][a-zA-Z_0-9.[\]#-]*`. In simpler terms, they should
start with characters from the English alphabet or `_`, and can continue with same characters plus numbers and other accessors
like `.`, `[0]`, or `[#-1]`.
* The string literals (strings in the right side of the operators) can be either single or double quoted.
* Boolean literals are represented as `1` or `0`.
* The operators, boolean operators, and boolean literals are case insensitive.
# Indexes
Source: https://upstash.com/docs/search/features/indexes
Upstash Search allows you to partition a single database into multiple isolated indexes.
Each index acts as a self-contained subset of the database,
search and upsert requests are limited to one index.
***
## Using an Index
Indexes are created implicitly when an upsert operation is performed,
so there is no specific endpoint for creating an index.
For example, the code snippet below will create the index `foo` if it does not already exist,
upsert and search the document only on that index.
```python
index = client.index("foo")
index.upsert( ... )
```
```ts
const index = client.index("movies");
await index.upsert( ... );
```
***
## Listing Indexes
Names of all the active indexes of a database can be listed as follows:
```python
client.list_indexes()
```
```ts
await client.listIndexes()
```
***
## Deleting an Index
Leftover indexes can be deleted as follows:
```python
client.delete_index("foo")
```
```ts
await client.index("foo").deleteIndex();
```
# Reranking
Source: https://upstash.com/docs/search/features/reranking
Upstash Search combines semantic and full text search results for maximum relevancy. Optionally, you can re-rank the returned documents using a state of the art model to further improve relevancy.
We provide this additional re-ranking as an opt-in setting because it requires more computational resources and is charged at \$1 per 1K re-ranked documents.
```python
scores = index.search(
query="space opera",
limit=2,
reranking=True,
)
```
```ts
const searchResults = await index.search({
query: "space opera",
limit: 2,
reranking: true,
});
```
# FAQ
Source: https://upstash.com/docs/search/help/faq
Questions And Answers About Upstash Search
***
## Upload & Storage
**How can I upload a large dataset quickly?**
To upload large datasets efficiently, write a script that upserts documents in batches of 100.
**What is the maximum size or number of documents I can index?**
You can index an unlimited number of documents, though the entire database is capped at 50GB. Each document can contain up to 1,500 characters.
**How is storage calculated and charged?**
We charge based on the number of documents you store, not the storage size they take up.
***
## Search & Indexing
**Do you support full-text search?**
Yes, we support full-text search through special embedding models called sparse indexes that simulate full-text search capabilities within the vector space.
**What is the maximum number of search indexes I can create?**
You can create up to 10,000 indexes per database.
**How do I remove specific fields from an indexed document?**
You can simply upsert the same document without the unwanted fields. When you remove or rewrite records, their associated indexes are automatically removed if they are empty.
***
## Billing
**If I upload documents but don't perform searches, will I still be charged?**
Yes, you'll be charged for the number of documents you store, regardless of whether you perform searches on them.
**How are searches and document updates counted for billing?**
Both searches and document updates are counted as requests and charged at the same rate as document creation.
**If a single query returns multiple documents, how is that counted for billing?**
A query that returns multiple documents counts as a single request. If you enable reranking, you'll be charged based on the number of documents reranked, with pricing per 100-document units. For example, reranking 99 documents costs 1 unit, while reranking 101 documents costs 2 units.
# Getting Started
Source: https://upstash.com/docs/search/overall/getstarted
Creating an Upstash Search Database
***
***
## Quickstart
Check out our Next.js quickstart guide if you're working in Next.js.
Use Upstash Search in your Next.js app
***
## Create a Database
Create a Search Database by navigating to the `Search` tab and clicking on the `Create Database` button.
A dialog with the following options will open:
* **Name:** Type a name for your database (e.g. "product-search").
* **Region:** Choose the region for your database. For best performance, select the region closest to your application.
*We plan to support additional regions and cloud providers. Feel free to send your requests to [support@upstash.com](mailto:support@upstash.com).*
Once you're done, click `Next`, choose a plan, and your Database is ready:
***
## Add Documents
Add documents to your database using our REST API, our SDKs, or directly in the dashboard.
### 1. Add Documents via Dashboard
Navigate to the `Data Browser` section of your Database and click `Upsert Documents`:
A dialog with the following options will open:
* **Index:** An [index](/search/features/indexes) to group your data.
*If you plan to query all documents in one place, you only need one index (e.g. "product-search"). If you plan to add multi-tenancy, so that each user can only search their own data, for example, you can create one index per user ("user-1", "user-2", etc.).*
* **ID:** An automatically generated ID.
* **Content:** The searchable data in JSON format.
* **Metadata:** Optional information attached to this document.
More information about content and metadata can be found [here](/search/features/content-and-metadata).
***
### 2. Add Documents via SDKs
```python
from upstash_search import Search
client = Search(
url="",
token="",
)
index = client.index("movies")
index.upsert(
documents=[
{
"id": "movie-0",
"content": {
"title": "Star Wars",
"overview": "Sci-fi space opera",
"genre": "sci-fi",
"category": "classic",
},
"metadata": {
"poster": "https://poster.link/starwars.jpg",
},
},
],
)
```
```ts
import { Search } from "@upstash/search"
const client = new Search({
url: "",
token: "",
})
const index = client.index("movies")
await index.upsert([
{
id: "star-wars",
content: { title: "Star Wars", genre: "sci-fi", category: "classic" },
metadata: { director: "George Lucas" },
},
])
```
***
## Search Your Database
You can search across your Database the same way: using our REST API, our SDKs or directly in your dashboard.
### 1. Searching via Dashboard
To search your documents, enter a search term and click `Search`:
### 2. Searching Data via SDKs
`py scores = index.search( query="space opera", limit=2, ) `
```ts
const searchResults = await index.search({
query: "space opera",
limit: 2,
reranking: true,
});
```
***
**That's it!** š You've just created your first serverless search database with Upstash Search!
But this is just the beginning. Upstash Search also supports:
* Advanced reranking
* Fine-grained control over search results
* Metadata-based filtering
We'll get into those features in the next sections of this documentation. For now, you've already mastered the basics!
# Pricing & Limits
Source: https://upstash.com/docs/search/overall/pricing
Please check our [pricing page](https://upstash.com/pricing/search) for the most up-to-date information on pricing and limits.
# What is Upstash Search?
Source: https://upstash.com/docs/search/overall/whatisupstashsearch
Lightweight, AI-powered search for developers
Upstash Search is a **simple, lightweight, and scalable way to add AI-powered search to your app**.
We combine full-text and semantic search for highly relevant results. Search works out of the box and scales to massive data sizes with zero infrastructure to manage.
***
## Lightweight & Efficient
Most search products (we'll avoid names here š) are bloated, complicated, and hard to manage. We're building Upstash search to be the exact opposite: fast to set up, easy to use and optimized for real-world use cases.
* Set up in minutes
* Plug-and-play AI search with smart defaults
* Optimized for speed and simplicity
***
## Fast, Relevant Results
We have a deep understanding of LLM technology through [Upstash Vector](https://upstash.com/docs/vector/overall/whatisvector) and hosting our own models at scale. We're now using that experience to make search feel truly intelligent. While most search products add AI to catch up, we're making it a core part of Upstash Search from the start.
* Combines semantic & full-text search for relevancy
* Understands user search intent
* Smart ranking shows the best matches first
***
## Scales Automatically
We've scaled [Upstash Redis](https://upstash.com/docs/redis/overall/getstarted) to serve billions of requests each day with extremely high availability. That same experience is built into Search, so you never have to think about infra.
We're building Search for modern, serverless stacks from the ground up. It's ready for any data size you throw at it.
* Perfect for serverless apps and modern frameworks like Next.js
* Scales to any data size (seriously, we've indexed the entire Wikipedia in 7 languages)
* No infrastructure, clusters or servers to manage
***
## Start using Upstash Search
Whether you're building a side project or scaling your company, Upstash Search gives you fast, smart, production-ready search with zero infra to manage. Try it today, it only takes a few minutes to [get started](/search/overall/getstarted.mdx)!
# Delete
Source: https://upstash.com/docs/search/sdks/py/commands/delete
## Delete Command for Python SDK
The delete method allows you to delete documents from your index using various criteria.
### Arguments
One or more document IDs to delete.
A string prefix to match document IDs for deletion. All documents with IDs starting with this prefix will be deleted.
A [filter](/search/features/filtering) to delete documents based on content fields.
Deleting document with filter is a O(N) operation that performs a full
scan. Therefore, it might be slow for large indexes.
### Response
The number of documents that were successfully deleted.
```typescript Delete by IDs Array
index.delete(ids=["star-wars", "inception"]);
```
```typescript Delete by Prefix
index.delete(prefix="star-");
```
```typescript Delete with Filter
index.delete(filter="age > 30");
```
# Fetch
Source: https://upstash.com/docs/search/sdks/py/commands/fetch
## Fetch Command for Python SDK
Used to retrieve documents by their IDs.
### Arguments
The IDs of the documents you want to fetch.
An ID prefix to match document IDs.
### Response
This field is `null` if no document with the specified ID is found.
The ID of the resulting document.
The main content of the document.
Additional metadata for the document.
```python By ID
documents = index.fetch(ids=["movie-0", "movie-1"])
print(documents)
```
```python ID Prefix
documents = index.fetch(prefix=["movie-"])
print(documents)
```
# Info
Source: https://upstash.com/docs/search/sdks/py/commands/info
## Info Command for Python SDK
Used to retrieve the stats of an index.
### Response
The total number of documents in the database, that are ready to use.
The number of documents in the database, that are still processing and not ready to use.
Size of the database in bytes.
Doctionary of index names and their information (`document_count` and `pending_document_count`)
```python
from upstash_search import Search
client = Search(
url="",
token="",
)
info = client.info()
print(info)
```
# Range
Source: https://upstash.com/docs/search/sdks/py/commands/range
## Range Command for Python SDK
The range method is used to retrieve documents in chunks with pagination.
### Arguments
The cursor to the last retrieved document. Should be set to `""` in the initial range request.
The number of maximum documents wanted in the response of range. (page size)
### Response
This field is `null` if no document with the specified ID is found.
The ID of the resulting document.
The main content of the document.
Additional metadata for the document.
The cursor for the next page of documents.
```python
range_documents = index.range(cursor="", limit=1)
print(range_documents.documents)
range_documents = index.range(
cursor=range_documents.next_cursor,
limit=3
)
print(range_documents.documents)
```
# Reset
Source: https://upstash.com/docs/search/sdks/py/commands/reset
## Reset Command for Python SDK
The `reset` method allows you to clear all documents from a particular index.
### Response
`'Success'` if the database is successfully reset.
```python
from upstash_search import Search
client = Search(
url="",
token="",
)
index = client.index("movies")
index.reset()
```
# Search
Source: https://upstash.com/docs/search/sdks/py/commands/search
## Search Command for Python SDK
The search method is designed to retrieve the most relevant documents from the database, using AI-powered search capabilities.
### Arguments
The search query string.
The maximum number of results to return. Defaults to 10.
Whether to enable AI-powered reranking of results. Disabled by default.
A [filter](/search/features/filtering) for narrowing down the search results based on content fields.
### Response
This field is `null` if no document with the specified ID is found.
The ID of the resulting document.
The main content of the document.
Additional metadata for the document.
Similarity score of the document
```python Basic Search
results = index.search(
query="space opera",
limit=2
)
print(results)
```
```python Search with Reranking
results = index.search(
query="space opera",
limit=2,
reranking=True
)
print(results)
```
```python Search with Filter
results = index.search(
query="space",
limit=2,
filter="category = 'classic'"
)
print(results)
```
# Upsert
Source: https://upstash.com/docs/search/sdks/py/commands/upsert
## Upsert Command for Python SDK
Used to add new documents or update an existing document.
### Arguments
The unique identifier for the document.
The main content of the document.
Additional metadata for the document.
```python
from upstash_search import Search
client = Search(
url="",
token="",
)
index = client.index("movies")
index.upsert(
documents=[
{
"id": "movie-0",
"content": {
"title": "Star Wars",
"overview": "Sci-fi space opera",
"genre": "sci-fi",
"category": "classic",
},
"metadata": {
"poster": "https://poster.link/starwars.jpg",
},
},
],
)
```
# Getting Started
Source: https://upstash.com/docs/search/sdks/py/gettingstarted
`upstash-search` is a Python SDK for Upstash AI Search, enabling easier operations on Search Databases.
Using `upstash-search` you can:
* Perform AI-powered search queries with or without reranking.
* Upsert documents with metadata to an index.
* Fetch documents by their IDs.
* Delete documents from a database.
* Access database stats.
* Reset everything related to a database.
You can find the GitHub Repository [here](https://github.com/upstash/search-py).
## Install
```bash
pip install upstash-search
```
## Usage
### Initializing the client
There are two pieces of configuration required to use the Upstash search client: a REST token and REST URL. These values can be passed using environment variables or in code through a configuration object. Find your configuration values in [the console dashboard](https://console.upstash.com/search).
#### Using environment variables
The environment variables used to configure the client are the following. You can follow [this guide](/search/overall/getstarted) to retrieve credentials.
```bash
UPSTASH_SEARCH_REST_URL="your_rest_url"
UPSTASH_SEARCH_REST_TOKEN="your_rest_token"
```
When these environment variables are set, the client constructor does not require any additional arguments.
```python
from upstash_search import Search
client = Search.from_env()
```
#### Using a configuration object
If you prefer to pass configuration in code, the constructor accepts a config object containing the `url` and `token` values. This
could be useful if your application needs to interact with multiple databases, each with a different configuration.
```python
from upstash_search import Search
client = Search(
url="",
token="",
)
```
***
### Using an Index
The `Search` client is for operations that are about manipulating the Search database. With it, you can create indexes which is where you can upsert and search documents.
```python
index = client.index("films")
index.upsert(
documents=[
{
"id": "movie-0",
"content": {
"title": "Star Wars",
"overview": "Sci-fi space opera",
"genre": "sci-fi",
"category": "classic",
},
"metadata": {
"poster": "https://poster.link/starwars.jpg",
},
},
],
)
```
# Delete
Source: https://upstash.com/docs/search/sdks/ts/commands/delete
The delete method allows you to delete documents from your index using various criteria. You can delete documents by their IDs, by ID prefix or with metadata filter.
## Arguments
One or more document IDs to delete.
**OR**
One or more document IDs to delete.
A string prefix to match document IDs for deletion. All documents with IDs starting with this prefix will be deleted.
A [filter](/search/features/filtering) to delete documents based on content fields.
Deleting document with filter is a O(N) operation that performs a full
scan. Therefore, it might be slow for large indexes.
## Response
The number of documents that were successfully deleted.
```typescript Delete by IDs Array
const response = await index.delete(["star-wars", "inception"]);
// { deleted: 2 }
```
```typescript Delete Single ID
const response = await index.delete("star-wars");
// { deleted: 1 }
```
```typescript Delete by Prefix
const response = await index.delete({
prefix: "star-",
});
// { deleted: 3 }
```
```typescript Delete with Filter
const response = await index.delete({
filter: "age > 30",
});
// { deleted: 3 }
```
# Fetch
Source: https://upstash.com/docs/search/sdks/ts/commands/fetch
Used to retrieve documents by their IDs.
## Arguments
The IDs of the documents you want to fetch.
**OR**
The IDs of the documents you want to fetch.
An ID prefix to match document IDs.
## Response
This field is `null` if no document with the specified ID is found.
The ID of the resulting document.
```typescript Basic
await index.fetch({ ids: ["star-wars", "inception"] });
/*
[
{
id: "star-wars",
content: { ... },
metadata: { ... }
},
{
id: "inception",
content: { ... },
metadata: { ... }
}
]
*/
```
```typescript ID prefix
await index.fetch({ prefix: "star-" });
/*
[
{
id: "star-wars"
content: { ... },
metadata: { ... }
},
{
id: "star-trek",
content: { ... },
metadata: { ... }
}
]
*/
```
# Info
Source: https://upstash.com/docs/search/sdks/ts/commands/info
When it comes to info requests, there are two alternatives. One for index level and one for database level.
## Index Info
Used to retrieve the stats of an index.
### Response
The total number of documents in the database, that are ready to use.
The number of documents in the database, that are still processing and not ready to use.
## Database Info
Alternatively, you can call `info` on the client itself, which will return information about the whole database:
### Response
The total number of documents in the database, that are ready to use.
The number of documents in the database, that is still processing and not ready to
use.
The size of the database, in `b`.
A map of indexes to their information in the following format
The total number of documents in the index, that are ready to use.
The number of documents in the index, that is still processing and not ready to
use.
```typescript Index
const client = new Search();
const index = client.index("movies");
const infoResponse = await index.info();
/*
{
documentCount: 100,
pendingDocumentCount: 5,
}
*/
```
```typescript Database
const client = new Search();
const infoResponse = await client.info();
/*
{
diskSize: 456890
pendingDocumentCount: 12,
documentCount: 120,
indexes: {
"movies": {
documentCount: 100,
pendingDocumentCount: 5
},
"actors": {
documentCount: 20,
pendingDocumentCount: 7
}
}
}
*/
```
# Range
Source: https://upstash.com/docs/search/sdks/ts/commands/range
The range method is used to retrieve documents in chunks with pagination. This method supports a variety of options to configure the query to your needs.
The range command is stateless, meaning you need to pass all of the parameters in each subsequent request.
## Arguments
The cursor to the last retrieved document. Should be set to `0` in the initial range request.
A string prefix to match document IDs. All documents with IDs that start with this prefix will be retrieved.
The number of maximum documents wanted in the response of range. (page size)
## Response
The cursor for the next set of documents. When it becomes "", it means all documents were retrieved.
The list of documents retrieved in this range.
```typescript Basic
const responseRange = await index.range({
cursor: "0",
limit: 2,
});
/*
{
nextCursor: '2',
documents: [
{ id: "doc1", content: { ... }, metadata: { ... } },
{ id: "doc2", content: { ... }, metadata: { ... } }
]
}
*/
```
```typescript ID prefix
const responseRange = await index.range({
cursor: "0",
limit: 2,
prefix: "test-",
});
/*
{
nextCursor: '2',
documents: [
{ id: "test-1", content: { ... }, metadata: { ... } },
{ id: "test-2", content: { ... }, metadata: { ... } }
]
}
*/
```
# Reset
Source: https://upstash.com/docs/search/sdks/ts/commands/reset
The `reset` method allows you to clear all documents from a particular index.
## Response
`'Success'` if the database is successfully reset.
```typescript Basic
const responseReset = await index.reset();
// 'Success'
```
# Search
Source: https://upstash.com/docs/search/sdks/ts/commands/search
The search method is designed to retrieve the most relevant documents from the database, using AI-powered search capabilities. This method supports a variety of options to configure the query to your needs.
The score returned from search requests is a normalized value between 0 and 1, where 1 indicates the highest relevance and 0 the lowest.
## Arguments
The search query string.
The maximum number of results to return. Defaults to 5.
Whether to enable AI-powered reranking of results. Disabled by default.
A [filter](/search/features/filtering) for narrowing down the search results based on content fields.
## Response
The list of documents matching the search query.
```typescript Basic Search
const searchResults = await index.search({
query: "space opera",
limit: 2,
});
console.log(searchResults);
```
```typescript Search with Reranking
const searchResults = await index.search({
query: "space opera",
limit: 2,
reranking: true,
});
console.log(searchResults);
```
```typescript Search with Filter
const searchResults = await index.search({
query: "space",
limit: 2,
filter: "category = 'classic'",
});
console.log(searchResults);
```
# Upsert
Source: https://upstash.com/docs/search/sdks/ts/commands/upsert
Used to add new documents or update an existing document.
You can only upsert documents with the same structure as defined in your database.
## Arguments
## Response
`'Success'` on successful operation.
```typescript Single Document
await index.upsert({
id: "star-wars",
content: { title: "Star Wars", genre: "sci-fi" },
metadata: { year: 1977 }
});
```
```typescript Multiple Documents
await index.upsert([
{
id: "inception",
content: { title: "Inception", genre: "action" }
metadata: {
year: 2010,
},
},
{ ... },
]);
```
```typescript Update Document
await index.upsert({
id: "star-wars",
content: {
title: "Star Wars: Episode IV - A New Hope",
genre: "sci-fi"
},
});
```
# Contributing
Source: https://upstash.com/docs/search/sdks/ts/contributing
## Preparing the environment
This project uses [Bun](https://bun.sh/) for packaging and dependency management. Make sure you have the relevant dependencies.
```commandline
curl -fsSL https://bun.sh/install | bash
```
You will also need a search database on [Upstash](https://console.upstash.com/search).
***
## Code Formatting
Run the following command to format code:
```bash
bun run fmt
```
***
## Running tests
To run all the tests, make sure you have the relevant environment variables.
```bash
bun run test
```
# Getting Started
Source: https://upstash.com/docs/search/sdks/ts/getting-started
`@upstash/search` is a TypeScript SDK for Upstash AI Search.
Using `@upstash/search` you can:
* Perform AI-powered search queries
* Upsert documents to an index
* Fetch documents by their IDs
* Delete documents from a database
* Access database stats
* Reset databases
You can find the GitHub Repository [here](https://github.com/upstash/search-js).
***
## Installation
```bash npm
npm install @upstash/search
```
```bash yarn
yarn add @upstash/search
```
```bash pnpm
pnpm add @upstash/search
```
```bash bun
bun install @upstash/search
```
***
## Usage
### Initializing the client
There are two pieces of configuration required to use the Upstash search client:
* a REST token
* a REST URL
These values can be passed using environment variables or through a configuration object. Find these connection details in [the console dashboard](https://console.upstash.com/search).
***
#### Using environment variables (recommended)
You can follow [this guide](/search/overall/getstarted) to retrieve the following credentials.
```bash
UPSTASH_SEARCH_REST_URL="your_rest_url"
UPSTASH_SEARCH_REST_TOKEN="your_rest_token"
```
When these environment variables are set, the client constructor does not require any additional arguments.
```typescript
import { Search } from "@upstash/search";
const client = Search.fromEnv();
const index = client.index("movies")
```
***
#### Using a configuration object
The `Search` class accepts a config object containing the `url` and `token` values. This
could be useful if your application needs to interact with multiple databases, each with a different configuration.
```typescript
import { Search } from "@upstash/search";
const client = new Search({
url: "",
token: "",
});
const index = client.index("movies")
```
***
#### Typescript
The Search SDK supports defining your content and metadata types at the index level for complete type-safety.
```typescript {4,5,6}
import { Search } from "@upstash/search";
const client = new Search();
type Content = { title: string, genre: string };
type Metadata = { year: number };
const index = client.index("movies");
await index.upsert({
id: "document-id",
content: { title: "Star Wars", genre: "sci-fi" },
metadata: { year: 1977 }
})
```
Passing a `Content` type at the index level will provide type safety for the content coming back from or required for the following commands:
* `search`
* `upsert`
* `fetch`
* `range`
In cases you don't want to define a content type at the index level, you can override the index level type definition for a specific command:
```typescript
const results = await index.upsert({
id: "id",
content: { title: "Movie title", ... }
});
```
# Next.js Search Quickstart
Source: https://upstash.com/docs/search/tutorials/nextjs
Getting Started With Upstash Search and Next.js
***
### 1. Create a Search Database
Follow the instructions in the [Getting Started guide](/search/overall/getstarted) to create a Search Database.
***
### 2. Project Setup
Let's create a new Next.js application and install the `@upstash/search` package:
```shell
npx create-next-app@latest search-app
cd search-app
npm install @upstash/search
```
***
### 3. Add Environment Variables
Find the environment variables from your database dashboard and add them to your `.env` file:
```bash
UPSTASH_SEARCH_REST_URL=
UPSTASH_SEARCH_REST_TOKEN=
```
***
### 4. Create an API Route to Upsert Documents
Create an API route in `app/api/upsert/route.ts`:
```typescript title="app/api/upsert/route.ts"
import { Search } from "@upstash/search"
const client = new Search({
url: process.env.UPSTASH_SEARCH_REST_URL,
token: process.env.UPSTASH_SEARCH_REST_TOKEN,
})
const index = client.index("my-index")
export async function POST() {
await index.upsert([
{
id: "movie-1",
content: {
title: "Inception",
description: "A thriller about dreams within dreams.",
},
metadata: { genre: "sci-fi", year: 2010 },
},
{
id: "movie-2",
content: {
title: "The Godfather",
description: "A story about a powerful Italian-American crime family.",
},
metadata: { genre: "crime", year: 1972 },
},
{
id: "movie-3",
content: {
title: "The Dark Knight",
description: "A tale of Batman's fight against the Joker.",
},
metadata: { genre: "action", year: 2008 },
},
])
return new Response("OK")
}
```
***
### 5. Create a Route to Search Documents
Create an API route in `app/api/search/route.ts`:
```typescript title="app/api/search/route.ts"
import { Search } from "@upstash/search"
const client = new Search({
url: process.env.UPSTASH_SEARCH_REST_URL,
token: process.env.UPSTASH_SEARCH_REST_TOKEN,
})
const index = client.index("my-index")
export async function POST(req: Request) {
const { query } = (await req.json()) as { query: string }
const results = await index.search({ query })
return new Response(JSON.stringify(results))
}
```
***
### 6. Create a Simple Page
Add the following code in `app/page.tsx`:
```typescript title="app/page.tsx"
"use client";
import { useState } from "react";
interface SearchResult {
id: string;
content: Record;
metadata: Record;
score: number;
}
export default function Home() {
const [searchResults, setSearchResults] = useState
For example, if the prefix is `@strapi`, the key will be `@strapi:
For example, `["GET", "POST"]`
Some examples:
* `path: "/api/restaurants/:id"`
* `path: "/api/restaurants"`
Available sources are:
* `ip`: The IP address of the user.
* `header`: The value of a header key. You should pass the source in the `header.
For example, `header.Authorization` will use the value of the `Authorization`
* `fixed-window`: The fixed-window algorithm divides time into fixed intervals. Each interval has a set limit of allowed requests. When a new interval starts, the count resets.
* `sliding-window`: The sliding-window algorithm uses a rolling time frame. It considers requests from the past X time units, continuously moving forward. This provides a smoother distribution of requests over time.
* `token-bucket`: The token-bucket algorithm uses a bucket that fills with tokens at a steady rate. Each request consumes a token. If the bucket is empty, requests are denied. This allows for bursts of traffic while maintaining a long-term rate limit.
For example, `20s` means 20 seconds.
**For more information, check**:
[https://developers.cloudflare.com/workers/runtime-apis/web-standards](https://developers.cloudflare.com/workers/runtime-apis/web-standards)
In the next page, choose `Nodejs 12` as your runtime, `npm install` as your
build command, `node server` as your start command and `8080` as your port.
The next page configures your App Runner service. Set a name for your service.
Set your Redis URL that you copied from Upstash console as `REDIS_URL`
environment variable. Your Redis URL should be something like this:
`rediss://:d34baef614b6fsdeb01b25@us1-lasting-panther-33618.upstash.io:33618`
You can leave other settings as default.
Click on `Create and Deploy` at the next page. Your service will be ready in a
few minutes. Click on the default domain, you should see the page with a view
counter as [here](https://xmzuanrpf3.us-east-1.awsapprunner.com/).
### App Runner vs AWS Lambda
* AWS Lambda runs functions, App Runner runs applications. So with App Runner
you do not need to split your application to functions.
* App Runner is a more portable solution. You can move your application from App
Runner to any other container service.
* AWS Lambda price scales to zero, App Runner's does not. With App Runner you
need to pay for an at least one instance unless you pause the system.
App Runner is great alternative when you need more control on your serverless
runtime and application. Check out
[this video](https://www.youtube.com/watch?v=x_1X_4j16A4) to learn more about
App Runner.
# Session Management on Google Cloud Run with Serverless Redis
Source: https://upstash.com/docs/redis/tutorials/cloud_run_sessions
This tutorial shows how to manage user sessions on Google Cloud Run using Serverless Redis.
Developers are moving their apps to serverless architectures and one of the most
common questions is
[how to store user sessions](https://stackoverflow.com/questions/57711095/are-users-sessions-on-google-cloud-run-apps-directed-to-the-same-instance).
You need to keep your state and session data in an external data store because
serverless environments are stateless by design. Unfortunately most of the
databases are not serverless friendly. They do not support per-request pricing
or they require heavy and persistent connections. These also explain the
motivations why we built Upstash. Upstash is a serverless Redis database with
per-request pricing, durable storage.
In this article I will write a basic web application which will run on Google
Cloud Run and keep the user sessions in Upstash Redis. Google Cloud Run provides
Serverless Container service which is also stateless. Cloud Run is more powerful
than serverless functions (AWS Lambda, Cloud Functions) as you can run your own
container. But you can not guarantee that the same container instance will
process the requests of the same user. So you need to keep the user session in
an external storage. Redis is the most popular choice to keep the session data
thanks to its speed and simplicity. Upstash gives you the serverless Redis
database which fits perfectly to your serverless stack.
If you want to store your session data manually on Redis, check
[here](https://upstash.com/docs/redis/tutorials/using_google_cloud_functions). But in
this article I will use [Express session](https://github.com/expressjs/session)
middleware which can work with Redis for user session management.
Here is the [live demo.](https://cloud-run-sessions-dr7fcdmn3a-uc.a.run.app)
Here is the
[source code](https://github.com/upstash/examples/tree/master/examples/cloud-run-sessions)
## The Stack
Serverless processing: Google Cloud Run
Serverless data: Upstash
Web framework: Express
## Project Setup
Create a directory for your project:
```
mkdir cloud-run-sessions
cd cloud-run-sessions
```
Create a node project and install dependencies:
```
npm init
npm install express redis connect-redis express-session
```
Create a Redis DB from [Upstash](https://console.upstash.com). In the database
details page, click the Connect button, copy the connection code (Node.js
node-redis).
If you do not have it already, install Google Cloud SDK as described
[here.](https://cloud.google.com/sdk/docs/install) Set the project and enable
Google Run and Build services:
```
gcloud config set project cloud-run-sessions
gcloud services enable run.googleapis.com
gcloud services enable cloudbuild.googleapis.com
```
## The Code
Create index.js and update as below:
```javascript
var express = require("express");
var parseurl = require("parseurl");
var session = require("express-session");
const redis = require("redis");
var RedisStore = require("connect-redis")(session);
var client = redis.createClient({
// REPLACE HERE
});
var app = express();
app.use(
session({
store: new RedisStore({ client: client }),
secret: "forest squirrel",
resave: false,
saveUninitialized: true,
})
);
app.use(function (req, res, next) {
if (!req.session.views) {
req.session.views = {};
}
// get the url pathname
var pathname = parseurl(req).pathname;
// count the views
req.session.views[pathname] = (req.session.views[pathname] || 0) + 1;
next();
});
app.get("/", function (req, res, next) {
res.send("you viewed this page " + req.session.views["/"] + " times");
});
app.get("/foo", function (req, res, next) {
res.send("you viewed this page " + req.session.views["/foo"] + " times");
});
app.get("/bar", function (req, res, next) {
res.send("you viewed this page " + req.session.views["/bar"] + " times");
});
app.listen(8080, function () {
console.log("Example app listening on port 8080!");
});
```
Run the app: `node index.js`
Check [http://localhost:3000/foo](http://localhost:3000/foo) in different
browsers to validate it keeps the session.
Add the start script to your `package.json`:
```json
"scripts": {
"test": "echo \"Error: no test specified\" && exit 1",
"start": "node index"
}
```
## Build
Create a Docker file (Dockerfile) in the project folder as below:
```
# Use the official lightweight Node.js 12 image.
# https://hub.docker.com/_/node
FROM node:12-slim
# Create and change to the app directory.
WORKDIR /usr/src/app
# Copy application dependency manifests to the container image.
# A wildcard is used to ensure both package.json AND package-lock.json are copied.
# Copying this separately prevents re-running npm install on every code change.
COPY package*.json ./
# Install dependencies.
RUN npm install
# Copy local code to the container image.
COPY . ./
# Run the web service on container startup.
CMD [ "npm", "start" ]
```
Build your container image:
```
gcloud builds submit --tag gcr.io/cloud-run-sessions/main
```
List your container images: `gcloud container images list`
Run the container locally:
```
gcloud auth configure-docker
docker run -d -p 8080:8080 gcr.io/cloud-run-sessions/main:v0.1
```
In case you have an issue on docker run, check
[here](https://cloud.google.com/container-registry/docs/troubleshooting).
## Deploy
Run:
```
gcloud run deploy cloud-run-sessions \
--image gcr.io/cloud-run-sessions/main:v0.1 \
--platform managed \
--region us-central1 \
--allow-unauthenticated
```
This command should give you
[the URL of your application](https://cloud-run-sessions-dr7fcdmn3a-uc.a.run.app)
as below:
```
Deploying container to Cloud Run service [cloud-run-sessions] in project [cloud-run-sessions] region [us-central1]
ā Deploying... Done.
ā Creating Revision...
ā Routing traffic...
ā Setting IAM Policy...
Done.
Service [cloud-run-sessions] revision [cloud-run-sessions-00006-dun] has been deployed and is serving 100 percent of traffic.
Service URL: https://cloud-run-sessions-dr7fcdmn3a-uc.a.run.app
```
## Cloud Run vs Cloud Functions
I have developed two small prototypes with both. Here my impression:
* Simplicity: Cloud functions are simpler to deploy as it does not require any
container building step.
* Portability: Cloud Run leverages your container, so anytime you can move your
application to any containerized system. This is a plus for Cloud Run.
* Cloud Run looks more powerful as it runs your own container with more
configuration options. It also allows running longer tasks (can be extended to
60 minutes)
* Cloud Run looks more testable as you can run the container locally. Cloud
Functions require a simulated environment.
Personally, I see Cloud Functions as a pure serverless solution where Cloud Run
is a hybrid solution. I would choose Cloud functions for simple, self contained
tasks or event driven solutions. If my use case is more complex with
portability/testability requirements, then I would choose Cloud Run.
# Cloudflare Workers with Websockets and Redis
Source: https://upstash.com/docs/redis/tutorials/cloudflare_websockets_redis
# Use Redis in Cloudflare Workers
Source: https://upstash.com/docs/redis/tutorials/cloudflare_workers_with_redis
## Motivation
We want to give a use case where you can use the GraphQL API without any backend
code. The use case is publicly available read only data for web applications
where you need low latency. The data is updated frequently by another backend
application, you want your users to see the last updated data. Examples:
Leaderboards, news list, blog list, product list, top N items in the homepages.
### `1` Project Setup:
Create a Next application: `npx create-next-app`.
Install Apollo GraphQL client: `npm i @apollo/client`
### `2` Database Setup
If you do not have one, create a database following this
[guide](../overall/getstarted). Connect your database via Redis CLI and run:
```shell
rpush coins '{ "name" : "Bitcoin", "price": 56819, "image": "https://s2.coinmarketcap.com/static/img/coins/64x64/1.png"}' '{ "name" : "Ethereum", "price": 2130, "image": "https://s2.coinmarketcap.com/static/img/coins/64x64/1027.png"}' '{ "name" : "Cardano", "price": 1.2, "image": "https://s2.coinmarketcap.com/static/img/coins/64x64/2010.png"}' '{ "name" : "Polkadot", "price": 35.96, "image": "https://s2.coinmarketcap.com/static/img/coins/64x64/6636.png"}' '{ "name" : "Stellar", "price": 0.506, "image": "https://s2.coinmarketcap.com/static/img/coins/64x64/512.png"}'
```
### `3` Code
In the Upstash console, copy the read only access key in your API configuration
page (GraphQL Explorer > Configure API). In the `_app.js` create the Apollo
client and replace the your access key as below:
Coin Price List
|
|
{item.name} | ${item.price} |
|
|
If it is working, you can deploy your app to AWS by running `sam deploy --guided`. Enter a stack name and pick your region. After confirming changes, the deployment should begin. The command will output API Gateway endpoint URL, check the API in your browser. You can also check your deployment on your AWS console. You will see your function has been created.
Click on your function, you will see the code is uploaded and API Gateway is configured. ### Notes * Check the template.yaml file. You can add new functions and APIGateway endpoints editing this file. * It is a good practice to keep your Redis endpoint and password as environment variable. * You can use [serverless framework](https://www.serverless.com/) instead of AWS SAM to deploy your function. # Build a Serverless Histogram API with Redis Source: https://upstash.com/docs/redis/tutorials/histogram This tutorial shows how to build a histogram API with Redis. While developing [the latency benchmark for the serverless databases (DynamoDB, FaunaDB, Upstash)](https://blog.upstash.com/latency-comparison), I wished there was an API where I will record the latency numbers and get the histogram back. In this tutorial, I will build such an API where you can record your latency values from any application. It will be a REST API with following methods: * record: Records numeric values into the histogram. * get: Returns the histogram object. ### Motivation I will show how easy to develop a generic API using AWS Lambda and Serverless Redis. See [code](https://github.com/upstash/examples/tree/master/examples/histogram-api). ### `1` Create a Redis (Upstash) Database Create a database as [getting started](../overall/getstarted) ### `2` Serverless Project Setup If you do not have it already install serverless framework via: `npm install -g serverless` In any folder run `serverless` as below: ```text >> serverless Serverless: No project detected. Do you want to create a new one? Yes Serverless: What do you want to make? AWS Node.js Serverless: What do you want to call this project? histogram-api Project successfully created in 'histogram-api' folder. You can monitor, troubleshoot, and test your new service with a free Serverless account. Serverless: Would you like to enable this? No You can run the āserverlessā command again if you change your mind later. ```
Counter: {count}
Edit src/App.js and save to reload.
***
## **Conclusion**
In this tutorial, we built a real-time chat application using Flask, SocketIO, and Upstash Redis. Redis, with its low latency and high throughput, is an ideal choice for real-time messaging systems.
To learn more about Upstash Redis, visit the [Upstash Redis Documentation](https://upstash.com/docs/redis).
# Manage Sessions in Python with Serverless Redis
Source: https://upstash.com/docs/redis/tutorials/python_session
In this tutorial, weāll see how to implement session management in a FastAPI application using Upstash Redis. Weāll use cookies to store session IDs, while session data is maintained in Redis for its speed and expiration features.
## **What Are Sessions and Cookies?**
* **Session:** A session is a mechanism to store user-specific data (like authentication status) between requests. It allows the server to "remember" users as they interact with the application.
* **Cookie:** A small piece of data stored in the clientās browser. In this tutorial, weāll use cookies to store session IDs, which the server uses to fetch session details from Redis.
## **Why Redis?**
Redis is a great choice for session management because:
1. **Fast Lookups:** Redis is an in-memory database, ensuring near-instantaneous access to session data.
2. **Expiration Control:** Built-in expiration functionality allows sessions to automatically expire after a defined timeout.
***
## **Setup**
### **1. Install the Required Libraries**
Install FastAPI, Upstash Redis, and other necessary dependencies:
```bash
pip install fastapi upstash-redis uvicorn python-dotenv
```
### **2. Create a Redis Database**
Create a Redis database using the [Upstash Console](https://console.upstash.com) or [Upstash CLI](https://github.com/upstash/cli).
Create a `.env` file in the root of your project with the following content:
```bash
UPSTASH_REDIS_REST_URL=your_upstash_redis_url
UPSTASH_REDIS_REST_TOKEN=your_upstash_redis_token
```
## **Code**
Let's implement a simple FastAPI application that handles login, profile access, and logout using Redis for session management. We use sliding expiration by updating the session expiration time on every request. If a session is inactive for 15 minutes (900 seconds), it will automatically expire.
```python main.py
from fastapi import FastAPI, Response, Cookie, HTTPException
from pydantic import BaseModel
from upstash_redis import Redis
from dotenv import load_dotenv
import uuid
# Load environment variables
load_dotenv()
redis = Redis.from_env()
app = FastAPI()
SESSION_TIMEOUT_SECONDS = 900 # 15 minutes
# Define the request body model for login
class LoginRequest(BaseModel):
username: str
@app.post("/login/")
async def login(request: LoginRequest, response: Response):
session_id = str(uuid.uuid4())
redis.hset(f"session:{session_id}", values={"user": request.username, "status": "active"})
redis.expire(f"session:{session_id}", SESSION_TIMEOUT_SECONDS)
response.set_cookie(key="session_id", value=session_id, httponly=True)
return {"message": "Logged in successfully", "session_id": session_id}
@app.get("/profile/")
async def get_profile(session_id: str = Cookie(None)):
if not session_id:
raise HTTPException(status_code=403, detail="No session cookie found")
session_data = redis.hgetall(f"session:{session_id}")
if not session_data:
response = Response()
response.delete_cookie(key="session_id") # Clear the expired cookie
raise HTTPException(status_code=404, detail="Session expired")
# Update the session expiration time (sliding expiration)
redis.expire(f"session:{session_id}", SESSION_TIMEOUT_SECONDS)
return {"session_id": session_id, "session_data": session_data}
@app.post("/logout/")
async def logout(response: Response, session_id: str = Cookie(None)):
if session_id:
redis.delete(f"session:{session_id}")
response.delete_cookie(key="session_id")
return {"message": "Logged out successfully"}
```
Let's test the implementation using the following script:
```python test_script.py
import requests
base_url = "http://127.0.0.1:8000"
# Test login
response = requests.post(f"{base_url}/login/", json={"username": "abdullah"})
print("Login Response:", response.json())
# In the browser, you don't need to set cookies manually. The browser will handle it automatically.
session_cookie = response.cookies.get("session_id")
# Test profile
profile_response = requests.get(f"{base_url}/profile/", cookies={"session_id": session_cookie})
print("Access Profile Response:", profile_response.json())
# Test logout
logout_response = requests.post(f"{base_url}/logout/", cookies={"session_id": session_cookie})
print("Logout Response:", logout_response.json())
# Test profile after logout
profile_after_logout_response = requests.get(f"{base_url}/profile/", cookies={"session_id": session_cookie})
print("Access Profile After Logout Response:", profile_after_logout_response.text)
```
***
### **Code Explanation**
1. **`/login/` Endpoint:**
* Generates a unique session ID using `uuid.uuid4()`.
* Stores the session data in Redis using the session ID as the key.
* Sets a cookie named `session_id` with the generated session ID.
* Returns a success message along with the session ID.
2. **`/profile/` Endpoint:**
* Retrieves the session ID from the cookie.
* Fetches the session data from Redis using the session ID.
* Updates the session expiration time.
* Returns the session ID and session data.
3. **`/logout/` Endpoint:**
* Deletes the session data from Redis using the session ID.
* Clears the `session_id` cookie.
***
### **Run the Application**
1. Start the FastAPI server:
```bash
uvicorn main:app --reload
```
2. Run the test script:
```bash
python test_script.py
```
Here's what you should expect:
```plaintext
Login Response: {'message': 'Logged in successfully', 'session_id': '68223c50-ede4-48eb-9d26-4a4dd735c10d'}
Access Profile Response: {'session_id': '68223c50-ede4-48eb-9d26-4a4dd735c10d', 'session_data': {'user': 'abdullah', 'status': 'active'}}
Logout Response: {'message': 'Logged out successfully'}
Access Profile After Logout Response: {"detail":"Session not found or expired"}
```
***
## **Conclusion**
By combining FastAPI, cookies, and Upstash Redis, weāve created a reliable session management system. With Redisās speed and built-in expiration features, this approach ensures secure and efficient handling of user sessions.
To learn more about Upstash Redis, visit the [Upstash Redis Documentation](https://upstash.com/docs/redis).
# Building a URL Shortener with Redis
Source: https://upstash.com/docs/redis/tutorials/python_url_shortener
### Introduction
In this tutorial, weāll build a simple URL shortener using Redis and Python. The short URL service will generate a random short code for each URL, store it in Redis, and allow users to retrieve the original URL using the short code. Weāll also implement an expiration time for each shortened URL, making it expire after a specified period.
### Environment Setup
First, install the necessary dependencies, including Upstash Redis and `python-dotenv` for environment variables:
```shell
pip install upstash-redis
```
### Database Setup
Create a Redis database using the [Upstash Console](https://console.upstash.com) or [Upstash CLI](https://github.com/upstash/cli), and export the `UPSTASH_REDIS_REST_URL` and `UPSTASH_REST_TOKEN` to your environment:
```shell
export UPSTASH_REDIS_REST_URL=
A dialog with the following options will open:
* **Name:** Type a name for your database (e.g. "product-search").
* **Region:** Choose the region for your database. For best performance, select the region closest to your application.
*We plan to support additional regions and cloud providers. Feel free to send your requests to [support@upstash.com](mailto:support@upstash.com).*
Once you're done, click `Next`, choose a plan, and your Database is ready:
***
## Add Documents
Add documents to your database using our REST API, our SDKs, or directly in the dashboard.
### 1. Add Documents via Dashboard
Navigate to the `Data Browser` section of your Database and click `Upsert Documents`:
A dialog with the following options will open:
* **Index:** An [index](/search/features/indexes) to group your data.
*If you plan to query all documents in one place, you only need one index (e.g. "product-search"). If you plan to add multi-tenancy, so that each user can only search their own data, for example, you can create one index per user ("user-1", "user-2", etc.).*
* **ID:** An automatically generated ID.
* **Content:** The searchable data in JSON format.
* **Metadata:** Optional information attached to this document.
More information about content and metadata can be found [here](/search/features/content-and-metadata).
***
### 2. Add Documents via SDKs
### 2. Searching Data via SDKs