Code Interpreter

{messages.map((message) => (

{message.role === "user" ? "You" : "Assistant"}

{message.parts.map((part, i) => { if (part.type === "text") { return (

{part.text}

); } if (part.type.startsWith("tool-")) { // eslint-disable-next-line @typescript-eslint/no-explicit-any const p = part as any; const toolName = part.type.slice(5); const isDone = p.state === "output-available"; return (

{toolName}{" "} {isDone ? "✓" : "running…"} {isDone && p.output && (

                        {String(p.output.output)}

)}

); } return null; })}

))}

It works!

", to: ["bar@outlook.com"], subject: "World Hello", html: "

It 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](/docs/qstash/howto/publishing) section for more technical details. ### Publish a message to an endpoint Simple example to [publish](/docs/qstash/howto/publishing) a message to an endpoint. ```shell curl -XPOST \ -H 'Authorization: Bearer XXX' \ -H "Content-type: application/json" \ -d '{ "hello": "world" }' \ 'https://qstash.upstash.io/v2/publish/https://example.com' ``` ```typescript const client = new Client({ token: "" }); await client.publishJSON({ url: "https://example.com", body: { hello: "world", }, }); ``` ```python from qstash import QStash client = QStash("") client.message.publish_json( url="https://example.com", body={ "hello": "world", }, ) # Async version is also available ``` ### Publish a message to a URL Group The [URL Group](/docs/qstash/features/url-groups) is a way to publish a message to multiple endpoints in a fan out pattern. ```shell curl -XPOST \ -H 'Authorization: Bearer XXX' \ -H "Content-type: application/json" \ -d '{ "hello": "world" }' \ 'https://qstash.upstash.io/v2/publish/myUrlGroup' ``` ```typescript const client = new Client({ token: "" }); await client.publishJSON({ urlGroup: "myUrlGroup", body: { hello: "world", }, }); ``` ```python from qstash import QStash client = QStash("") client.message.publish_json( url_group="my-url-group", body={ "hello": "world", }, ) # Async version is also available ``` ### Publish a message with 5 minutes delay Add a delay to the message to be published. After QStash receives the message, it will wait for the specified time (5 minutes in this example) before sending the message to the endpoint. ```shell curl -XPOST \ -H 'Authorization: Bearer XXX' \ -H "Content-type: application/json" \ -H "Upstash-Delay: 5m" \ -d '{ "hello": "world" }' \ 'https://qstash.upstash.io/v2/publish/https://example.com' ``` ```typescript const client = new Client({ token: "" }); await client.publishJSON({ url: "https://example.com", body: { hello: "world", }, delay: 300, }); ``` ```python from qstash import QStash client = QStash("") client.message.publish_json( url="https://example.com", body={ "hello": "world", }, delay="5m", ) # Async version is also available ``` ### Send a custom header Add a custom header to the message to be published. ```shell curl -XPOST \ -H 'Authorization: Bearer XXX' \ -H 'Upstash-Forward-My-Header: my-value' \ -H "Content-type: application/json" \ -d '{ "hello": "world" }' \ 'https://qstash.upstash.io/v2/publish/https://example.com' ``` ```typescript const client = new Client({ token: "" }); await client.publishJSON({ url: "https://example.com", body: { hello: "world", }, headers: { "My-Header": "my-value", }, }); ``` ```python from qstash import QStash client = QStash("") client.message.publish_json( url="https://example.com", body={ "hello": "world", }, headers={ "My-Header": "my-value", }, ) # Async version is also available ``` ### Schedule to run once a day ```shell curl -XPOST \ -H 'Authorization: Bearer XXX' \ -H "Upstash-Cron: 0 0 * * *" \ -H "Content-type: application/json" \ -d '{ "hello": "world" }' \ 'https://qstash.upstash.io/v2/schedules/https://example.com' ``` ```typescript const client = new Client({ token: "" }); await client.schedules.create({ destination: "https://example.com", cron: "0 0 * * *", }); ``` ```python from qstash import QStash client = QStash("") client.schedule.create( destination="https://example.com", cron="0 0 * * *", ) # Async version is also available ``` ### Publish messages to a FIFO queue By default, messges are published concurrently. With a [queue](/docs/qstash/features/queues), you can enqueue messages in FIFO order. ```shell curl -XPOST -H 'Authorization: Bearer XXX' \ -H "Content-type: application/json" \ 'https://qstash.upstash.io/v2/enqueue/my-queue/https://example.com' -d '{"message":"Hello, World!"}' ``` ```typescript const client = new Client({ token: "" }); const queue = client.queue({ queueName: "my-queue" }) await queue.enqueueJSON({ url: "https://example.com", body: { "Hello": "World" } }) ``` ```python from qstash import QStash client = QStash("") client.message.enqueue_json( queue="my-queue", url="https://example.com", body={ "Hello": "World", }, ) # Async version is also available ``` ### Publish messages in a [batch](/docs/qstash/features/batch) Publish multiple messages in a single request. ```shell curl -XPOST https://qstash.upstash.io/v2/batch \ -H 'Authorization: Bearer XXX' \ -H "Content-type: application/json" \ -d ' [ { "destination": "https://example.com/destination1" }, { "destination": "https://example.com/destination2" } ]' ``` ```typescript import { Client } from "@upstash/qstash"; const client = new Client({ token: "" }); const res = await client.batchJSON([ { url: "https://example.com/destination1", }, { url: "https://example.com/destination2", }, ]); ``` ```python from qstash import QStash client = QStash("") client.message.batch_json( [ { "url": "https://example.com/destination1", }, { "url": "https://example.com/destination2", }, ] ) # Async version is also available ``` ### Set max retry count to 3 Configure how many times QStash should retry to send the message to the endpoint before sending it to the [dead letter queue](/docs/qstash/features/dlq). ```shell curl -XPOST \ -H 'Authorization: Bearer XXX' \ -H "Upstash-Retries: 3" \ -H "Content-type: application/json" \ -d '{ "hello": "world" }' \ 'https://qstash.upstash.io/v2/publish/https://example.com' ``` ```typescript const client = new Client({ token: "" }); await client.publishJSON({ url: "https://example.com", body: { hello: "world", }, retries: 3, }); ``` ```python from qstash import QStash client = QStash("") client.message.publish_json( url="https://example.com", body={ "hello": "world", }, retries=3, ) # Async version is also available ``` ### Set custom retry delay Configure the delay between retry attempts when message delivery fails. [By default, QStash uses exponential backoff](/docs/qstash/features/retry). You can customize this using mathematical expressions with the special variable `retried` (current retry attempt count starting from 0). ```shell curl -XPOST \ -H 'Authorization: Bearer XXX' \ -H "Upstash-Retries: 3" \ -H "Upstash-Retry-Delay: pow(2, retried) * 1000" \ -H "Content-type: application/json" \ -d '{ "hello": "world" }' \ 'https://qstash.upstash.io/v2/publish/https://example.com' ``` ```typescript const client = new Client({ token: "" }); await client.publishJSON({ url: "https://example.com", body: { hello: "world", }, retries: 3, retryDelay: "pow(2, retried) * 1000", // 2^retried * 1000ms }); ``` ```python from qstash import QStash client = QStash("") client.message.publish_json( url="https://example.com", body={ "hello": "world", }, retries=3, retry_delay="pow(2, retried) * 1000", # 2^retried * 1000ms ) # Async version is also available ``` **Supported functions for retry delay expressions:** * `pow` - Power function * `sqrt` - Square root * `abs` - Absolute value * `exp` - Exponential * `floor` - Floor function * `ceil` - Ceiling function * `round` - Rounding function * `min` - Minimum of values * `max` - Maximum of values **Examples:** * `1000` - Fixed 1 second delay * `1000 * (1 + retried)` - Linear backoff: 1s, 2s, 3s, 4s... * `pow(2, retried) * 1000` - Exponential backoff: 1s, 2s, 4s, 8s... * `max(1000, pow(2, retried) * 100)` - Exponential with minimum 1s delay ### Set callback url Receive a response from the endpoint and send it to the specified callback URL. If the endpoint does not return a response, QStash will send it to the failure callback URL. ```shell curl -XPOST \ -H 'Authorization: Bearer XXX' \ -H "Content-type: application/json" \ -H "Upstash-Callback: https://example.com/callback" \ -H "Upstash-Failure-Callback: https://example.com/failure" \ -d '{ "hello": "world" }' \ 'https://qstash.upstash.io/v2/publish/https://example.com' ``` ```typescript const client = new Client({ token: "" }); await client.publishJSON({ url: "https://example.com", body: { hello: "world", }, callback: "https://example.com/callback", failureCallback: "https://example.com/failure", }); ``` ```python from qstash import QStash client = QStash("") client.message.publish_json( url="https://example.com", body={ "hello": "world", }, callback="https://example.com/callback", failure_callback="https://example.com/failure", ) # Async version is also available ``` ### Get message logs Retrieve logs for all messages that have been published (filtering is also available). ```shell curl https://qstash.upstash.io/v2/logs \ -H "Authorization: Bearer XXX" ``` ```typescript const client = new Client({ token: "" }); const logs = await client.logs() ``` ```python from qstash import QStash client = QStash("") client.event.list() # Async version is also available ``` ### List all schedules ```shell curl https://qstash.upstash.io/v2/schedules \ -H "Authorization: Bearer XXX" ``` ```typescript const client = new Client({ token: "" }); const scheds = await client.schedules.list(); ``` ```python from qstash import QStash client = QStash("") client.schedule.list() # Async version is also available ``` # Changelog Source: https://upstash.com/docs/qstash/overall/changelog We have moved the roadmap and the changelog to [Github Discussions](https://github.com/orgs/upstash/discussions) starting from October 2025.Now you can follow `In Progress` features. You can see that your `Feature Requests` are recorded. You can vote for them and comment your specific use-cases to shape the feature to your needs. * **TypeScript SDK (`qstash-js`)** and **Python SDK (`qstash-py`):** * Added flow control management API: `list()`, `get(key)`, and `reset(key)` methods on `client.flowControl` (TypeScript) and `client.flow_control` (Python). * The `get` and `list` responses now include rich metrics: `waitListSize`, `parallelismMax`, `parallelismCount`, `rateMax`, `rateCount`, `ratePeriod`, and `ratePeriodStart`. * See the [Flow Control](/docs/qstash/features/flowcontrol#management-api) docs for code examples. * **QStash Server:** * `GET /v2/flowControl` now supports an optional `search` query parameter to filter keys by name. * New `POST /v2/flowControl/:flowControlKey/reset` endpoint resets parallelism and rate counters for a key. * `GET /v2/globalParallelism` now returns `{ parallelismMax, parallelismCount }` instead of the old `{ waitListSize }` shape. * **TypeScript SDK (`qstash-js`):** * `Label` feature is added. This will enable our users to label their publishes so that * Logs can be filtered with user given label. * DLQ can be filtered with user given label. * **Console:** * `Flat view` on the `Logs` tab is removed. The purpose is to simplify the `Logs` tab. All the information is already available on the default(grouped) view. Let us know if there is something missing via Discord/Support so that we can fill in the gaps. * **Console:** * Added ability to hide/show columns on the Schedules tab. * Local mode is added to enable our users to use the console with their local development envrionment. See [docs](http://localhost:3000/qstash/howto/local-development) for details. * **TypeScript SDK (`qstash-js`):** * Added `retryDelay` option to dynamicaly program the retry duration of a failed message. The new parameter is available in publish/batch/enqueue/schedules. See [here](/docs/qstash/features/retry#custom-retry-delay) * Full changelog, including all fixes, is available [here](https://github.com/upstash/qstash-js/compare/v2.8.1...v2.8.2). * No new features for QStash this month. We are mostly focused on stability and performance. * **TypeScript SDK (`qstash-js`):** * Added `flow control period` and deprecated `ratePerSecond`. See [here](https://github.com/upstash/qstash-js/pull/237). * Added `IN_PROGRESS` state filter. See [here](https://github.com/upstash/qstash-js/pull/236). * Full changelog, including all fixes, is available [here](https://github.com/upstash/qstash-js/compare/v2.7.23...v2.8.1). * **Python SDK (`qstash-py`):** * Added `IN_PROGRESS` state filter. See [here](https://github.com/upstash/qstash-js/pull/236). * Added various missing features: Callback Headers, Schedule with Queue, Overwrite Schedule ID, Flow Control Period. See [here](https://github.com/upstash/qstash-py/pull/41). * Full changelog, including all fixes, is available [here](https://github.com/upstash/qstash-py/compare/v2.0.5...v3.0.0). * **Console:** * Improved logs tab behavior to prevent collapsing or unnecessary refreshes, increasing usability. * **QStash Server:** * Added support for filtering messages by `FlowControlKey` (Console and SDK support in progress). * Applied performance improvements for bulk cancel operations. * Applied performance improvements for bulk publish operations. * Fixed an issue where scheduled publishes with queues would reset queue parallelism to 1. * Added support for updating existing queue parallelisms even when the max queue limit is reached. * Applied several additional performance optimizations. * **QStash Server:** * Added support for `flow-control period`, allowing users to define a period for a given rate—up to 1 week. Previously, the period was fixed at 1 second. For example, `rate: 3 period: 1d` means publishes will be throttled to 3 per day. * Applied several performance optimizations. * **Console:** * Added `IN_PROGRESS` as a filter option when grouping by message ID, making it easier to query in-flight messages. See [here](/docs/qstash/howto/debug-logs#lifecycle-of-a-message) for an explanation of message states. * **TypeScript SDK (`qstash-js`):** * Renamed `events` to `logs` for clarity when referring to QStash features. `client.events()` is now deprecated, and `client.logs()` has been introduced. See [details here](https://github.com/upstash/qstash-js/pull/225). * For all fixes, see the full changelog [here](https://github.com/upstash/qstash-js/compare/v2.7.22...v2.7.23). * **QStash Server:** * Fixed an issue where messages with delayed callbacks were silently failing. Now, such messages are explicitly rejected during insertion. * **Python SDK (`qstash-py`):** * Flow Control Parallelism and Rate. See [here](https://github.com/upstash/qstash-py/pull/36) * Addressed a few minor bugs. See the full changelog [here](https://github.com/upstash/qstash-py/compare/v2.0.3...v2.0.5) * **QStash Server:** * Introduced RateLimit and Parallelism controls to manage the rate and concurrency of message processing. Learn more [here](/docs/qstash/features/flowcontrol). * Improved connection timeout detection mechanism to enhance scalability. * Added several new features to better support webhook use cases: * Support for saving headers in a URL group. See [here](/docs/qstash/howto/webhook#2-url-group). * Ability to pass configuration parameters via query strings instead of headers. See [here](/docs/qstash/howto/webhook#1-publish). * Introduced a new `Upstash-Header-Forward` header to forward all headers from the incoming request. See [here](/docs/qstash/howto/webhook#1-publish). * **Python SDK (`qstash-py`):** * Addressed a few minor bugs. See the full changelog [here](https://github.com/upstash/qstash-py/compare/v2.0.2...v2.0.3). * **Local Development Server:** * The local development server is now publicly available. This server allows you to test your Qstash setup locally. Learn more about the local development server [here](/docs/qstash/howto/local-development). * **Console:** * Separated the Workflow and QStash consoles for an improved user experience. * Separated their DLQ messages as well. * **QStash Server:** * The core team focused on RateLimit and Parallelism features. These features are ready on the server and will be announced next month after the documentation and SDKs are completed. * **TypeScript SDK (`qstash-js`):** * Added global headers to the client, which are automatically included in every publish request. * Resolved issues related to the Anthropics and Resend integrations. * Full changelog, including all fixes, is available [here](https://github.com/upstash/qstash-js/compare/v2.7.17...v2.7.20). * **Python SDK (`qstash-py`):** * Introduced support for custom `schedule_id` values. * Enabled passing headers to callbacks using the `Upstash-Callback-Forward-...` prefix. * Full changelog, including all fixes, is available [here](https://github.com/upstash/qstash-py/compare/v2.0.0...v2.0.1). * **Qstash Server:** * Finalized the local development server, now almost ready for public release. * Improved error reporting by including the field name in cases of invalid input. * Increased the maximum response body size for batch use cases to 100 MB per REST call. * Extended event retention to up to 14 days, instead of limiting to the most recent 10,000 events. Learn more on the [Pricing page](https://upstash.com/pricing/qstash). * **TypeScript SDK (qstash-js):** * Added support for the Anthropics provider and refactored the `api` field of `publishJSON`. See the documentation [here](/docs/qstash/integrations/anthropic). * Full changelog, including fixes, is available [here](https://github.com/upstash/qstash-js/compare/v2.7.14...v2.7.17). * **Qstash Server:** * Fixed a bug in schedule reporting. The Upstash-Caller-IP header now correctly reports the user’s IP address instead of an internal IP for schedules. * Validated the scheduleId parameter. The scheduleId must now be alphanumeric or include hyphens, underscores, or periods. * Added filtering support to bulk message cancellation. Users can now delete messages matching specific filters. See Rest API [here](/docs/qstash/api-reference/messages/bulk-cancel-messages). * Resolved a bug that caused the DLQ Console to become unusable when data was too large. * Fixed an issue with queues that caused them to stop during temporary network communication problems with the storage layer. * **TypeScript SDK (qstash-js):** * Fixed a bug on qstash-js where we skipped using the next signing key when the current signing key fails to verify the `upstash-signature`. Released with qstash-js v2.7.14. * Added resend API. See [here](/docs/qstash/integrations/resend). Released with qstash-js v2.7.14. * Added `schedule to queues` feature to the qstash-js. See [here](/docs/qstash/features/schedules#scheduling-to-a-queue). Released with qstash-js v2.7.14. * **Console:** * Optimized the console by trimming event bodies, reducing resource usage and enabling efficient querying of events with large payloads. * **Qstash Server:** * Began development on a new architecture to deliver faster event processing on the server. * Added more fields to events in the [REST API](/docs/qstash/api-reference/logs/list-logs), including `Timeout`, `Method`, `Callback`, `CallbackHeaders`, `FailureCallback`, `FailureCallbackHeaders`, and `MaxRetries`. * Enhanced retry backoff logic by supporting additional headers for retry timing. Along with `Retry-After`, Qstash now recognizes `X-RateLimit-Reset`, `X-RateLimit-Reset-Requests`, and `X-RateLimit-Reset-Tokens` as backoff time indicators. See [here](/docs/qstash/features/retry#retry-after-headers) for more details. * Improved performance, resulting in reduced latency for average publish times. * Set the `nbf` (not before) claim on Signing Keys to 0. This claim specifies the time before which the JWT must not be processed. Previously, this was incorrectly used, causing validation issues when there were minor clock discrepancies between systems. * Fixed queue name validation. Queue names must now be alphanumeric or include hyphens, underscores, or periods, consistent with other API resources. * Resolved bugs related to [overwriting a schedule](/docs/qstash/features/schedules#overwriting-an-existing-schedule). * Released [Upstash Workflow](/docs/qstash/workflow). * Fixed a bug where paused schedules were mistakenly resumed after a process restart (typically occurring during new version releases). * Big update on the UI, where all the Rest functinality exposed in the Console. * Addded order query parameter to [/v2/events](/docs/qstash/api-reference/logs/list-logs) and [/v2/dlq](/docs/qstash/api-reference/dlq/list-dlq-messages) endpoints. * Added [ability to configure](/docs/qstash/features/callbacks#configuring-callbacks) callbacks(/failure_callbacks) * A critical fix for schedule pause and resume Rest APIs where the endpoints were not working at all before the fix. * Pause and resume for scheduled messages * Pause and resume for queues * [Bulk cancel](/docs/qstash/api-reference/messages/bulk-cancel-messages) messages * Body and headers on [events](/docs/qstash/api-reference/logs/list-logs) * Fixed inaccurate queue lag * [Retry-After](/docs/qstash/features/retry#retry-after-header) support for rate-limited endpoints * [Upstash-Timeout](/docs/qstash/api-reference/messages/publish-a-message) header * [Queues and parallelism](/docs/qstash/features/queues) * [Event filtering](/docs/qstash/api-reference/logs/list-logs) * [Batch publish messages](/docs/qstash/api-reference/messages/batch-messages) * [Bulk delete](/docs/qstash/api-reference/dlq/bulk-delete-dlq-messages) for DLQ * Added [failure callback support](/docs/qstash/api-reference/schedules/create-a-schedule) to scheduled messages * Added Upstash-Caller-IP header to outgoing messages. See [https://upstash.com/docs/qstash/howto/receiving] for all headers * Added Schedule ID to [events](/docs/qstash/api-reference/logs/list-logs) and [messages](/docs/qstash/api-reference/messages/get-a-message) * Put last response in DLQ * DLQ [get message](/docs/qstash/api-reference/dlq/delete-a-dlq-message) * Pass schedule ID to the header when calling the user's endpoint * Added more information to [callbacks](/docs/qstash/features/callbacks) * Added [Upstash-Failure-Callback](/docs/qstash/features/callbacks#what-is-a-failure-callback) # Compare Source: https://upstash.com/docs/qstash/overall/compare In this section, we will compare QStash with alternative solutions. ### BullMQ BullMQ is a message queue for NodeJS based on Redis. BullMQ is open source project, you can run BullMQ yourself. * Using BullMQ in serverless environments is problematic due to stateless nature of serverless. QStash is designed for serverless environments. * With BullMQ, you need to run a stateful application to consume messages. QStash calls the API endpoints, so you do not need your application to consume messages continuously. * You need to run and maintain BullMQ and Redis yourself. QStash is completely serverless, you maintain nothing and pay for just what you use. ### Zeplo Zeplo is a message queue targeting serverless. Just like QStash it allows users to queue and schedule HTTP requests. While Zeplo targets serverless, it has a fixed monthly price in paid plans which is \$39/month. In QStash, price scales to zero, you do not pay if you are not using it. With Zeplo, you can send messages to a single endpoint. With QStash, in addition to endpoint, you can submit messages to a URL Group which groups one or more endpoints into a single namespace. Zeplo does not have URL Group functionality. ### Quirrel Quirrel is a job queueing service for serverless. It has a similar functionality with QStash. Quirrel is acquired by Netlify, some of its functionality is available as Netlify scheduled functions. QStash is platform independent, you can use it anywhere. # Prod Pack & Enterprise Source: https://upstash.com/docs/qstash/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 add-on is available for both pay-as-you-go and fixed-price plans. Enterprise plans are custom plans with additional features and higher limits. All features of Prod Pack and Enterprise plan for Upstash QStash are detailed below. ## How to Upgrade You can activate Prod Pack in the QStash settings page in the [Upstash Console](https://console.upstash.com/qstash). For the Enterprise plan, please create a request through the Upstash Console or contact [support@upstash.com](mailto:support@upstash.com). # Prod Pack Features Below QStash features are enabled with Prod Pack. ### Uptime SLA All Prod Pack accounts come with an SLA guaranteeing 99.99% uptime. For mission-critical messaging where uptime is crucial, we recommend Prod Pack plans. Learn more about [Uptime SLA](/docs/common/help/sla). ### SOC-2 Type 2 Compliance & Report Upstash QStash is SOC-2 Type 2 compliant with Prod Pack. Once you enable Prod Pack, you can request access to the report by going to [Upstash Trust Center](https://trust.upstash.com/) or contacting [support@upstash.com](mailto:support@upstash.com). ### Encryption at Rest Encrypts the storage where your QStash message data is persisted and stored. ### 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 QStash messages with Prometheus in addition to console metrics. Learn more about [Prometheus integration](/docs/qstash/integrations/prometheus). ### Datadog Integration Upstash Prod Pack and Enterprise plans include integration with Datadog, allowing you to monitor your QStash messages with Datadog in addition to console metrics. Learn more about [Datadog integration](/docs/qstash/integrations/datadog). # Enterprise Features All Prod Pack features are included in the Enterprise plan. Additionally, Enterprise plans include: ### 100M+ Messages Daily Enterprise plans support 100 million or more messages per day, suitable for high-volume production workloads. ### Unlimited Bandwidth Enterprise plans include unlimited bandwidth, ensuring no data transfer limits for your messaging needs. ### SAML 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. ### Professional Support with SLA Enterprise plans include access to our professional support with response time SLAs and priority access to our support team. Check out the [support page](/docs/common/help/prosupport) for more details. ### Dedicated Resources for Isolation Enterprise customers receive dedicated resources to ensure isolation and consistent performance for their messaging workloads. # Getting Started Source: https://upstash.com/docs/qstash/overall/getstarted QStash is a **serverless messaging and scheduling solution**. It fits easily into your existing workflow and allows you to build reliable systems without managing infrastructure. Instead of calling an endpoint directly, QStash acts as a middleman between you and an API to guarantee delivery, perform automatic retries on failure, and more. We have a new SDK called [Upstash Workflow](/docs/workflow/getstarted). **Upstash Workflow SDK** is **QStash** simplified for your complex applications * Skip the details of preparing a complex dependent endpoints. * Focus on the essential parts. * Enjoy automatic retries and delivery guarantees. * Avoid platform-specific timeouts. Check out [Upstash Workflow Getting Started](/docs/workflow/getstarted) for more. ## Quick Start Check out these Quick Start guides to get started with QStash in your application. Build a Next application that uses QStash to start a long-running job on your platform Build a Python application that uses QStash to schedule a daily job that clean up a database Or continue reading to learn how to send your first message! ## Send your first message **Prerequisite** You need an Upstash account before publishing messages, create one [here](https://console.upstash.com). ### Public API Make sure you have a publicly available HTTP API that you want to send your messages to. If you don't, you can use something like [requestcatcher.com](https://requestcatcher.com/), [webhook.site](https://webhook.site/) or [webhook-test.com](https://webhook-test.com/) to try it out. For example, you can use this URL to test your messages: [https://firstqstashmessage.requestcatcher.com](https://firstqstashmessage.requestcatcher.com) ### Get your token Go to the [Upstash Console](https://console.upstash.com/qstash) and copy the `QSTASH_TOKEN`. ### 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](/docs/qstash/howto/publishing). ```bash cURL curl -XPOST \ -H 'Authorization: Bearer ' \ -H "Content-type: application/json" \ -d '{ "hello": "world" }' \ 'https://qstash.upstash.io/v2/publish/https://' ``` ```bash cURL RequestCatcher curl -XPOST \ -H 'Authorization: Bearer ' \ -H "Content-type: application/json" \ -d '{ "hello": "world" }' \ 'https://qstash.upstash.io/v2/publish/https://firstqstashmessage.requestcatcher.com/test' ``` Don't worry, we have SDKs for different languages so you don't have to make these requests manually. ### Check Response You should receive a response with a unique message ID. ### 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](/docs/qstash/howto/debug-logs). ## Features and Use Cases Run long-running tasks in the background, without blocking your application Schedule messages to be delivered at a time in the future Publish messages to multiple endpoints, in parallel, using URL Groups Enqueue messages to be delivered one by one in the order they have enqueued. Custom rate per second and parallelism limits to avoid overflowing your endpoint. Get a response delivered to your API when a message is delivered Use a Dead Letter Queue to have full control over failed messages Prevent duplicate messages from being delivered Publish, enqueue, or batch chat completion requests using large language models with QStash features. # llms.txt Source: https://upstash.com/docs/qstash/overall/llms-txt # Pricing & Limits Source: https://upstash.com/docs/qstash/overall/pricing Please check our [pricing page](https://upstash.com/pricing/qstash) for the most up-to-date information on pricing and limits. # Roadmap Source: https://upstash.com/docs/qstash/overall/roadmap We have moved the roadmap and the changelog to [Github Discussions](https://github.com/orgs/upstash/discussions) starting from October 2025.Now you can follow `In Progress` features. You can see that your `Feature Requests` are recorded. You can vote for them and comment your specific use-cases to shape the feature to your needs. # Use Cases Source: https://upstash.com/docs/qstash/overall/usecases TODO: andreas: rework and reenable this page after we have 2 use cases ready https://linear.app/upstash/issue/QSTH-84/use-cases-summaryhighlights-of-recipes This section is still a work in progress. We will be adding detailed tutorials for each use case soon. Tell us on [Discord](https://discord.gg/w9SenAtbme) or [X](https://x.com/upstash) what you would like to see here. ### Triggering Nextjs Functions on a schedule Create a schedule in QStash that runs every hour and calls a Next.js serverless function hosted on Vercel. ### Reset Billing Cycle in your Database Once a month, reset database entries to start a new billing cycle. ### Fanning out alerts to Slack, email, Opsgenie, etc. Createa QStash URL Group that receives alerts from a single source and delivers them to multiple destinations. ### Send delayed message when a new user signs up Publish delayed messages whenever a new user signs up in your app. After a certain delay (e.g. 10 minutes), QStash will send a request to your API, allowing you to email the user a welcome message. - [AWS Lambda (Node)](https://upstash.com/docs/qstash/quickstarts/aws-lambda/nodejs.md) - [AWS Lambda (Python)](https://upstash.com/docs/qstash/quickstarts/aws-lambda/python.md) - [Cloudflare Workers](https://upstash.com/docs/qstash/quickstarts/cloudflare-workers.md) - [Deno Deploy](https://upstash.com/docs/qstash/quickstarts/deno-deploy.md) - [Golang](https://upstash.com/docs/qstash/quickstarts/fly-io/go.md) - [Python on Vercel](https://upstash.com/docs/qstash/quickstarts/python-vercel.md) - [Next.js](https://upstash.com/docs/qstash/quickstarts/vercel-nextjs.md) - [Periodic Data Updates](https://upstash.com/docs/qstash/recipes/periodic-data-updates.md) - [DLQ](https://upstash.com/docs/qstash/sdks/py/examples/dlq.md) - [Events](https://upstash.com/docs/qstash/sdks/py/examples/events.md) - [Flow Control](https://upstash.com/docs/qstash/sdks/py/examples/flow-control.md) - [Keys](https://upstash.com/docs/qstash/sdks/py/examples/keys.md) - [Messages](https://upstash.com/docs/qstash/sdks/py/examples/messages.md) - [Overview](https://upstash.com/docs/qstash/sdks/py/examples/overview.md) - [Publish](https://upstash.com/docs/qstash/sdks/py/examples/publish.md) - [Queues](https://upstash.com/docs/qstash/sdks/py/examples/queues.md) - [Receiver](https://upstash.com/docs/qstash/sdks/py/examples/receiver.md) - [Schedules](https://upstash.com/docs/qstash/sdks/py/examples/schedules.md) - [URL Groups](https://upstash.com/docs/qstash/sdks/py/examples/url-groups.md) # Getting Started Source: https://upstash.com/docs/qstash/sdks/py/gettingstarted ## Install ### PyPI ```bash pip install qstash ``` ## Get QStash token Follow the instructions [here](/docs/qstash/overall/getstarted) to get your QStash token and signing keys. ## Usage #### Synchronous Client ```python from qstash import QStash client = QStash("") client.message.publish_json(...) ``` #### Asynchronous Client ```python import asyncio from qstash import AsyncQStash async def main(): client = AsyncQStash("") await client.message.publish_json(...) asyncio.run(main()) ``` #### RetryConfig You can configure the retry policy of the client by passing the configuration to the client constructor. Note: This isn for sending the request to QStash, not for the retry policy of QStash. The default number of retries is **5** and the default backoff function is `lambda retry_count: math.exp(retry_count) * 50`. You can also pass in `False` to disable retrying. ```python from qstash import QStash client = QStash( "", retry={ "retries": 3, "backoff": lambda retry_count: (2**retry_count) * 20, }, ) ``` # Overview Source: https://upstash.com/docs/qstash/sdks/py/overview `qstash` is an Python SDK for QStash, allowing for easy access to the QStash API. Using `qstash` you can: * Publish a message to a URL/URL group/API * Publish a message with a delay * Schedule a message to be published * Access logs for the messages that have been published * Create, read, update, or delete URL groups. * Read or remove messages from the [DLQ](/docs/qstash/features/dlq) * Read or cancel messages * Verify the signature of a message You can find the Github Repository [here](https://github.com/upstash/qstash-py). - [DLQ](https://upstash.com/docs/qstash/sdks/ts/examples/dlq.md) - [Flow Control](https://upstash.com/docs/qstash/sdks/ts/examples/flow-control.md) - [Logs](https://upstash.com/docs/qstash/sdks/ts/examples/logs.md) - [Messages](https://upstash.com/docs/qstash/sdks/ts/examples/messages.md) - [Overview](https://upstash.com/docs/qstash/sdks/ts/examples/overview.md) - [Publish](https://upstash.com/docs/qstash/sdks/ts/examples/publish.md) - [Queues](https://upstash.com/docs/qstash/sdks/ts/examples/queues.md) - [Receiver](https://upstash.com/docs/qstash/sdks/ts/examples/receiver.md) - [Schedules](https://upstash.com/docs/qstash/sdks/ts/examples/schedules.md) - [URL Groups](https://upstash.com/docs/qstash/sdks/ts/examples/url-groups.md) # Getting Started Source: https://upstash.com/docs/qstash/sdks/ts/gettingstarted ## Install ### NPM ```bash npm install @upstash/qstash ``` ## Get QStash token Follow the instructions [here](/docs/qstash/overall/getstarted) to get your QStash token and signing keys. ## Usage ```typescript import { Client } from "@upstash/qstash"; const client = new Client({ token: "", }); ``` #### RetryConfig You can configure the retry policy of the client by passing the configuration to the client constructor. Note: This is for sending the request to QStash, not for the retry policy of QStash. The default number of attempts is **6** and the default backoff function is `(retry_count) => (Math.exp(retry_count) * 50)`. You can also pass in `false` to disable retrying. ```typescript import { Client } from "@upstash/qstash"; const client = new Client({ token: "", retry: { retries: 3, backoff: retry_count => 2 ** retry_count * 20, }, }); ``` ## Local development Pass `devMode: true` (or set `QSTASH_DEV=true`) to have the SDK download, start, and manage a local QStash dev server for you. No tokens or signing keys required — the SDK injects deterministic dev credentials. ```typescript import { Client } from "@upstash/qstash"; const client = new Client({ devMode: true }); ``` The same flag works on the receiving side — pass `devMode: true` to `Receiver` or `verifySignature*` to verify signatures with the dev server's keys. See [Local Development](/docs/qstash/howto/local-development) for the full walkthrough, including the `registerQStashDev()` helper for Next.js edge routes. ## Telemetry This sdk sends anonymous telemetry headers to help us improve your experience. We collect the following: * SDK version * Platform (Cloudflare, AWS or Vercel) * Runtime version (node@18.x) You can opt out by setting the `UPSTASH_DISABLE_TELEMETRY` environment variable to any truthy value. Or setting `enableTelemetry: false` in the client options. ```ts const client = new Client({ token: "", enableTelemetry: false, }); ``` # Overview Source: https://upstash.com/docs/qstash/sdks/ts/overview `@upstash/qstash` is a Typescript SDK for QStash, allowing for easy access to the QStash API. Using `@upstash/qstash` you can: * Publish a message to a URL/URL Group * Publish a message with a delay * Schedule a message to be published * Access logs for the messages that have been published * Create, read, update, or delete URL groups. * Read or remove messages from the [DLQ](/docs/qstash/features/dlq) * Read or cancel messages * Verify the signature of a message You can find the Github Repository [here](https://github.com/upstash/sdk-qstash-ts). # Channels Source: https://upstash.com/docs/realtime/features/channels Channels allow you to scope events to specific people or rooms. For example: * Chat rooms * Emitting events to a specific user ## Default Channel By default, events are sent to the `default` channel. If we emit an event without specifying a channel like so: ```typescript await realtime.emit("notification.alert", "hello world!") ``` it can automatically be read using the default channel: ```typescript useRealtime({ events: ["notification.alert"], onData({ event, data, channel }) { console.log(data) }, }) ``` *** ## Custom Channels Emit events to a specific channel: ```typescript route.ts const channel = realtime.channel("user-123") await channel.emit("notification.alert", "hello world!") ``` Subscribe to one or more channels: ```tsx page.tsx "use client" import { useRealtime } from "@/lib/realtime-client" export default function Page() { useRealtime({ channels: ["user-123"], events: ["notification.alert"], onData({ event, data, channel }) { console.log(data) }, }) return <>... } ``` ## Channel Patterns Send notifications to individual users: ```typescript route.ts const channel = realtime.channel(`user-${userId}`) await channel.emit("notification.alert", "hello world!") ``` ```typescript page.tsx useRealtime({ channels: [`user-${user.id}`], events: ["notification.alert"], onData({ data }) {}, }) ``` Broadcast to all users in a room: ```typescript route.ts await realtime.channel(`room-${roomId}`).emit("room.message", { text: "Hello everyone!", sender: "Alice", }) ``` Scope events to team workspaces: ```typescript route.ts await realtime.channel(`team-${teamId}`).emit("project.update", { project: "Website Redesign", status: "In Progress", }) ``` ## Dynamic Channels Subscribe to multiple channels at the same time: ```tsx page.tsx "use client" import { useState } from "react" import { useRealtime } from "@/lib/realtime-client" export default function Page() { const [channels, setChannels] = useState(["lobby"]) useRealtime({ channels, events: ["chat.message"], onData({ event, data, channel }) { console.log(`Message from ${channel}:`, data) }, }) const joinRoom = (roomId: string) => { setChannels((prev) => [...prev, roomId]) } const leaveRoom = (roomId: string) => { setChannels((prev) => prev.filter((c) => c !== roomId)) } return (

Active channels: {channels.join(", ")}

) } ``` ## Broadcasting to Multiple Channels Emit to multiple channels at the same time: ```typescript route.ts const rooms = ["lobby", "room-1", "room-2"] await Promise.all( rooms.map((room) => { const channel = realtime.channel(room) return channel.emit("chat.message", `Hi channel ${room}!`) }) ) ``` ## Channel Security Combine channels with [middleware](/docs/realtime/features/middleware) for secure access control: ```typescript title="app/api/realtime/route.ts" import { handle } from "@upstash/realtime" import { realtime } from "@/lib/realtime" import { currentUser } from "@/auth" export const GET = handle({ realtime, middleware: async ({ request, channels }) => { const user = await currentUser(request) for (const channel of channels) { if (!user.canAccessChannel(channel)) { return new Response("Unauthorized", { status: 401 }) } } }, }) ``` See the middleware documentation for authentication examples # Client-Side Usage Source: https://upstash.com/docs/realtime/features/client-side The `useRealtime` hook connects your React components to realtime events with full type safety. ## Setup ### 1. Add the Provider Wrap your app in the `RealtimeProvider`: ```tsx providers.tsx "use client" import { RealtimeProvider } from "@upstash/realtime/client" export function Providers({ children }: { children: React.ReactNode }) { return {children} } ``` ```tsx layout.tsx import { Providers } from "./providers" export default function RootLayout({ children }: { children: React.ReactNode }) { return ( {children} ) } ``` ### 2. Create Typed Hook Create a typed `useRealtime` hook using `createRealtime`: ```typescript lib/realtime-client.ts "use client" import { createRealtime } from "@upstash/realtime/client" import type { RealtimeEvents } from "./realtime" export const { useRealtime } = createRealtime() ``` ## Basic Usage Subscribe to events in any client component: ```tsx page.tsx "use client" import { useRealtime } from "@/lib/realtime-client" export default function Page() { useRealtime({ events: ["notification.alert"], onData({ event, data, channel }) { console.log(`Received ${event}:`, data) }, }) return

Listening for events...

} ``` ## Provider Options API configuration: - `url`: The realtime endpoint URL - `withCredentials`: Whether to send cookies with requests Maximum number of reconnection attempts before giving up ```tsx providers.tsx "use client" import { RealtimeProvider } from "@upstash/realtime/client" export function Providers({ children }: { children: React.ReactNode }) { return ( {children} ) } ``` ## Hook Options Array of event names to subscribe to (e.g. `["notification.alert", "chat.message"]`) Callback when an event is received. Receives an object with `event`, `data`, and `channel`. Array of channel names to subscribe to Whether the subscription is active. Set to `false` to disconnect. ## Return Value The hook returns an object with: Current connection state: `"connecting"`, `"connected"`, `"disconnected"`, or `"error"` ```tsx page.tsx import { useRealtime } from "@/lib/realtime-client" const { status } = useRealtime({ events: ["notification.alert"], onData({ event, data, channel }) {}, }) console.log(status) ``` ## Connection Control Enable or disable connections dynamically: ```tsx page.tsx "use client" import { useState } from "react" import { useRealtime } from "@/lib/realtime-client" export default function Page() { const [enabled, setEnabled] = useState(true) const { status } = useRealtime({ enabled, events: ["notification.alert"], onData({ event, data, channel }) { console.log(event, data, channel) }, }) return (

Status: {status}

) } ``` ### Conditional Connections Connect only when certain conditions are met: ```tsx page.tsx "use client" import { useRealtime } from "@/lib/realtime-client" import { useUser } from "@/hooks/auth" export default function Page() { const { user } = useUser() useRealtime({ enabled: Boolean(user), channels: [`user-${user?.id}`], events: ["notification.alert"], onData({ event, data, channel }) { console.log(data) }, }) return

Notifications {user ? "enabled" : "disabled"}

} ``` ## Multiple Events Subscribe to multiple events at once: ```tsx page.tsx "use client" import { useRealtime } from "@/lib/realtime-client" export default function Page() { useRealtime({ events: ["chat.message", "chat.reaction", "user.joined"], onData({ event, data, channel }) { // 👇 data is automatically typed based on the event if (event === "chat.message") console.log("New message:", data) if (event === "chat.reaction") console.log("New reaction:", data) if (event === "user.joined") console.log("User joined:", data) }, }) return

Listening to multiple events

} ``` ## Multiple Channels Subscribe to multiple channels at once: ```tsx page.tsx "use client" import { useRealtime } from "@/lib/realtime-client" export default function Page() { useRealtime({ channels: ["global", "announcements", "user-123"], events: ["notification.alert"], onData({ event, data, channel }) { console.log(`Message from ${channel}:`, data) }, }) return

Listening to multiple channels

} ``` ### Dynamic Channel Management Add and remove channels dynamically: ```tsx page.tsx "use client" import { useState } from "react" import { useRealtime } from "@/lib/realtime-client" export default function Page() { const [channels, setChannels] = useState(["lobby"]) useRealtime({ channels, events: ["chat.message"], onData({ event, data, channel }) { console.log(`Message from ${channel}:`, data) }, }) const joinRoom = (roomId: string) => { setChannels((prev) => [...prev, roomId]) } const leaveRoom = (roomId: string) => { setChannels((prev) => prev.filter((c) => c !== roomId)) } return (

Active channels: {channels.join(", ")}

) } ``` ## Custom API Endpoint Configure a custom realtime endpoint in the provider: ```tsx providers.tsx "use client" import { RealtimeProvider } from "@upstash/realtime/client" export function Providers({ children }: { children: React.ReactNode }) { return ( {children} ) } ``` ## Use Cases Show real-time notifications to users: ```tsx notifications.tsx "use client" import { useRealtime } from "@/lib/realtime-client" import { toast } from "react-hot-toast" import { useUser } from "@/hooks/auth" export default function Notifications() { const { user } = useUser() useRealtime({ channels: [`user-${user.id}`], events: ["notification.alert"], onData({ data }) { toast(data) }, }) return

Listening for notifications...

} ``` Build a real-time chat: ```tsx chat.tsx "use client" import { useState } from "react" import { useRealtime } from "@/lib/realtime-client" import z from "zod/v4" import type { RealtimeEvents } from "@/lib/realtime" type Message = z.infer export default function Chat() { const [messages, setMessages] = useState([]) useRealtime({ channels: ["room-123"], events: ["chat.message"], onData({ data }) { setMessages((prev) => [...prev, data]) }, }) return (

{messages.map((msg, i) => (

{msg.sender}: {msg.text}

))}

) } ``` Update metrics in real-time: ```tsx dashboard.tsx "use client" import { useQuery, useQueryClient } from "@tanstack/react-query" import { useRealtime } from "@/lib/realtime-client" export default function Dashboard() { const queryClient = useQueryClient() const { data: metrics } = useQuery({ queryKey: ["metrics"], queryFn: async () => { const res = await fetch("/api/metrics?user=user-123") return res.json() }, }) useRealtime({ channels: ["user-123"], events: ["metrics.update"], onData() { queryClient.invalidateQueries({ queryKey: ["metrics"] }) }, }) return (

Active Users: {metrics?.users}

Revenue: ${metrics?.revenue}

) } ``` Sync changes across users: ```tsx editor.tsx "use client" import { useState } from "react" import { useRealtime } from "@/lib/realtime-client" export default function Editor({ documentId }: { documentId: string }) { const [content, setContent] = useState("") useRealtime({ channels: [`doc-${documentId}`], events: ["document.update"], onData({ data }) { setContent(data.content) }, }) return

setContent(e.target.value)} />
    }
    ```

</Accordion>
</AccordionGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Channels" icon="tower-broadcast" href="/realtime/features/channels">
    Scope events to specific rooms or users
  </Card>

<Card title="History" icon="clock-rotate-left" href="/realtime/features/history">
    Configure message retention and replay
  </Card>
</CardGroup>

# History
Source: https://upstash.com/docs/realtime/features/history

Message history allows you to retrieve past events and replay them to clients on connection. This is useful for making sure clients always have the latest state.

## Overview

All Upstash Realtime messages are automatically stored in Redis Streams. This way, messages are always delivered correctly, even after reconnects or network interruptions.

Clients can fetch past events and optionally subscribe to new events.

## Configuration

```typescript lib/realtime.ts
import { Realtime } from "@upstash/realtime"
import { redis } from "./redis"
import z from "zod/v4"

const schema = {
  chat: {
    message: z.object({
      text: z.string(),
      sender: z.string(),
    }),
  },
}

export const realtime = new Realtime({
  schema,
  redis,
  history: {
    maxLength: 100,
    expireAfterSecs: 86400,
  },
})
```

<ParamField path="maxLength" type="number" default="Infinite">
  Maximum number of messages to retain per channel. Example: `maxLength: 100` will keep
  the last 100 messages in the stream and automatically remove older messages as new ones
  are added.
</ParamField>

<ParamField path="expireAfterSecs" type="number" default="Infinite">
  How long to keep messages per channel before deleting them (in seconds). Resets every
  time a message is emitted to this channel.
</ParamField>

## Server-Side History

Retrieve and process history on the server:

```typescript route.ts
import { realtime } from "@/lib/realtime"

export const GET = async () => {
  const messages = await realtime.channel("room-123").history()

return new Response(JSON.stringify(messages))
}
```

### History Options

<ParamField path="limit" type="number" default="1000">
  Maximum number of messages to retrieve (capped at 1000)
</ParamField>

<ParamField path="start" type="number">
  Fetch messages after this Unix timestamp (in milliseconds)
</ParamField>

<ParamField path="end" type="number">
  Fetch messages before this Unix timestamp (in milliseconds)
</ParamField>

```typescript route.ts
const messages = await realtime.channel("room-123").history({
  limit: 50,
  start: Date.now() - 86400000,
})
```

### History Response

Each history message contains:

```typescript
type HistoryMessage = {
  id: string
  event: string
  channel: string
  data: unknown
}
```

### Subscribe with History

You can automatically replay past messages when subscribing to a channel:

```typescript route.ts
await realtime.channel("room-123").subscribe({
  events: ["chat.message"],
  history: true,
  onData({ event, data, channel }) {
    console.log("Message from room-123:", data)
  },
})
```

Pass history options for more control:

```typescript route.ts
await realtime.channel("room-123").subscribe({
  events: ["chat.message"],
  history: {
    limit: 50,
    start: Date.now() - 3600000,
  },
  onData({ data }) {
    console.log("Message:", data)
  },
})
```

## Use Cases

<AccordionGroup>
  <Accordion title="Chat Application">
    Load recent messages when a user joins a room:

<Info>We recommend keeping long chat histories in a database (e.g. Redis) and only fetching the latest messages from Upstash Realtime.</Info>

```tsx page.tsx
    "use client"

import { useRealtime } from "@/lib/realtime-client"
    import { useState, useEffect } from "react"
    import z from "zod/v4"
    import type { RealtimeEvents } from "@/lib/realtime"

type Message = z.infer<RealtimeEvents["chat"]["message"]>

export default function ChatRoom({ roomId }: { roomId: string }) {
      const [messages, setMessages] = useState<Message[]>([])

useEffect(() => {
        fetch(`/api/history?channel=${roomId}`)
          .then((res) => res.json())
          .then((history) => setMessages(history.map((m: any) => m.data)))
      }, [roomId])

useRealtime({
        channels: [roomId],
        events: ["chat.message"],
        onData({ data }) {
          setMessages((prev) => [...prev, data])
        },
      })

return (
        <div>
          {messages.map((msg, i) => (
            <div key={i}>
              <strong>{msg.sender}:</strong> {msg.text}
            </div>
          ))}
        </div>
      )
    }
    ```

</Accordion>

<Accordion title="Notification Center">
    Show unread notifications with history:

```tsx notifications.tsx
    "use client"

import { useRealtime } from "@/lib/realtime-client"
    import { useUser } from "@/hooks/auth"
    import { useState, useEffect } from "react"
    import z from "zod/v4"
    import type { RealtimeEvents } from "@/lib/realtime"

type Notification = z.infer<RealtimeEvents["notification"]["alert"]>

export default function Notifications() {
      const user = useUser()
      const [notifications, setNotifications] = useState<Notification[]>([])

useEffect(() => {
        fetch(`/api/history?channel=user-${user.id}`)
          .then((res) => res.json())
          .then((history) => {
            const unread = history.filter((m: any) => m.data.status === "unread")
            setNotifications(unread.map((m: any) => m.data))
          })
      }, [user.id])

useRealtime({
        channels: [`user-${user.id}`],
        events: ["notification.alert"],
        onData({ data }) {
          if (data.status === "unread") {
            setNotifications((prev) => [...prev, data])
          }
        },
      })

return (
        <div>
          {notifications.map((notif, i) => (
            <div key={i}>{notif}</div>
          ))}
        </div>
      )
    }
    ```

</Accordion>

<Accordion title="Live Activity Feed">
    Replay recent activity when users visit:

```tsx activity-feed.tsx
    "use client"

import { useRealtime } from "@/lib/realtime-client"
    import { useTeam } from "@/hooks/team"
    import { useState, useEffect } from "react"
    import z from "zod/v4"
    import type { RealtimeEvents } from "@/lib/realtime"

type Activity = z.infer<RealtimeEvents["activity"]["update"]>

export default function ActivityFeed() {
      const team = useTeam()
      const [activities, setActivities] = useState<Activity[]>([])

useEffect(() => {
        fetch(`/api/history?channel=team-${team.id}&limit=100`)
          .then((res) => res.json())
          .then((history) => setActivities(history.map((m: any) => m.data)))
      }, [team.id])

useRealtime({
        channels: [`team-${team.id}`],
        events: ["activity.update"],
        onData({ data }) {
          setActivities((prev) => [data, ...prev])
        },
      })

return (
        <div>
          {activities.map((activity, i) => (
            <div key={i}>{activity.message}</div>
          ))}
        </div>
      )
    }
    ```

</Accordion>
</AccordionGroup>

## How It Works

1. When you emit an event, it's stored in a Redis Stream with a unique stream ID
2. The stream is trimmed to `maxLength` if configured
3. The stream expires after `expireAfterSecs` if configured
4. History can be fetched via `channel.history()` on the server
5. History is replayed in chronological order (oldest to newest)
6. New events continue streaming right after history replay, no messages lost

## Performance Considerations

Upstash Realtime can handle extremely large histories without problems. The bottleneck is the client who needs to handle all replayed events.

At that point you should probably consider using a database like Redis or Postgres to fetch the history once, then stream new events to the client with Upstash Realtime.

<AccordionGroup>
  <Accordion title="Limit History Length">
    For high-volume channels, limit history to prevent large initial payloads.

```typescript lib/realtime.ts
    export const realtime = new Realtime({
      schema,
      redis,
      history: {
        maxLength: 1000,
      },
    })
    ```

</Accordion>

<Accordion title="Set Expiration">
    Expire old messages to reduce storage:

```typescript lib/realtime.ts
    export const realtime = new Realtime({
      schema,
      redis,
      history: {
        expireAfterSecs: 3600,
      },
    })
    ```

</Accordion>

</AccordionGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Server-Side Usage" icon="server" href="/realtime/features/server-side">
    Stream history and subscribe to events on the server
  </Card>

<Card title="Channels" icon="tower-broadcast" href="/realtime/features/channels">
    Scope history to specific rooms or users
  </Card>
</CardGroup>

# Authentication
Source: https://upstash.com/docs/realtime/features/middleware

Protect your realtime endpoints with custom auth logic.

## Basic Middleware

```typescript api/realtime/route.ts
import { handle } from "@upstash/realtime"
import { realtime } from "@/lib/realtime"
import { currentUser } from "@/auth"

export const GET = handle({
  realtime,
  middleware: async ({ request, channels }) => {
    const user = await currentUser(request)

if (!user) {
      return new Response("Unauthorized", { status: 401 })
    }
  },
})
```

## Middleware API

The middleware function receives:

<ParamField path="request" type="Request">
  The incoming HTTP Request object
</ParamField>

<ParamField path="channels" type="string[]" default="['default']">
  The channels a user is attempting to connect to
</ParamField>

<ResponseField name="return">
  * Return `undefined` or nothing to allow the connection
  * Return a `Response` object to block the connection with a custom error
</ResponseField>

## Authentication Patterns

<AccordionGroup>
  <Accordion title="User-Based Auth">
    Verify users can access specific channels:

```typescript api/realtime/route.ts
    export const GET = handle({
      realtime,
      middleware: async ({ request, channels }) => {
        const user = await currentUser(request)

for (const channel of channels) {
          if (channel === "default") {
            continue
          }

if (!channel.startsWith(user.id)) {
            return new Response("You can only access your own channels", { status: 403 })
          }
        }
      },
    })
    ```

</Accordion>

<Accordion title="Session-Based Auth">
    Verify user sessions before allowing connections:

```typescript api/realtime/route.ts
    import { getSession } from "@/auth"

export const GET = handle({
      realtime,
      middleware: async ({ request }) => {
        const session = await getSession(request)

if (!session?.user) {
          return new Response("Please sign in", { status: 401 })
        }
      },
    })
    ```

</Accordion>

<Accordion title="Role-Based Access">
    Control access based on user roles:

```typescript api/realtime/route.ts
    export const GET = handle({
      realtime,
      middleware: async ({ request, channels }) => {
        const user = await currentUser(request)

for (const channel of channels) {
          if (channel === "default") {
            continue
          }

if (channel.startsWith("admin-") && user.role !== "admin") {
            return new Response("Admin access required", { status: 403 })
          }

if (channel.startsWith("team-")) {
            const teamId = channel.replace("team-", "")
            const isMember = await checkTeamMembership(user.id, teamId)

if (!isMember) {
              return new Response("Not a team member", { status: 403 })
            }
          }
        }
      },
    })
    ```

</Accordion>
</AccordionGroup>

# Server-Side Usage
Source: https://upstash.com/docs/realtime/features/server-side

Use Upstash Realtime on the server to emit events, subscribe to channels, and retrieve message history.

## Emit Events

Emit events from any server context:

```typescript route.ts
import { realtime } from "@/lib/realtime"

export const POST = async () => {
  await realtime.emit("notification.alert", "hello world!")

return new Response("OK")
}
```

Emit to specific channels:

```typescript route.ts
import { realtime } from "@/lib/realtime"

export const POST = async () => {
  const channel = realtime.channel("user-123")
  await channel.emit("notification.alert", "hello world!")

return new Response("OK")
}
```

## Subscribe to Events

Subscribe to events on a channel:

```typescript route.ts
import { realtime } from "@/lib/realtime"

const unsubscribe = await realtime.channel("notifications").subscribe({
  events: ["notification.alert"],
  onData({ event, data, channel }) {
    console.log("New notification:", data)
  },
})
```

Subscribe to multiple events:

```typescript route.ts
import { realtime } from "@/lib/realtime"

const unsubscribe = await realtime.channel("room-123").subscribe({
  events: ["chat.message", "user.joined", "user.left"],
  onData({ event, data, channel }) {
    // 👇 data is automatically typed based on the event
    if (event === "chat.message") console.log("New message:", data)
    if (event === "user.joined") console.log("User joined:", data)
    if (event === "user.left") console.log("User left:", data)
  },
})
```

### Unsubscribe

Clean up subscriptions when done:

```typescript route.ts
import { realtime } from "@/lib/realtime"

const channel = realtime.channel("room-123")

const unsubscribe = await channel.subscribe({
  events: ["chat.message"],
  onData({ data }) {
    console.log("Message:", data)
  },
})

unsubscribe()
// or: channel.unsubscribe()
```

## Retrieve History

Fetch past messages from a channel:

```typescript route.ts
import { realtime } from "@/lib/realtime"

export const GET = async () => {
  const messages = await realtime.channel("room-123").history()

return new Response(JSON.stringify(messages))
}
```

### History Options

<ParamField path="limit" type="number" default="1000">
  Maximum number of messages to retrieve (capped at 1000)
</ParamField>

<ParamField path="start" type="number">
  Fetch messages after this Unix timestamp (in milliseconds)
</ParamField>

<ParamField path="end" type="number">
  Fetch messages before this Unix timestamp (in milliseconds)
</ParamField>

```typescript route.ts
const messages = await realtime.channel("room-123").history({
  limit: 100,
  start: Date.now() - 86400000,
})
```

### History Response

Each history message contains:

```typescript
type HistoryMessage = {
  id: string
  event: string
  channel: string
  data: unknown
}
```

## Subscribe with History

Replay past messages and continue subscribing to new ones:

```typescript route.ts
import { realtime } from "@/lib/realtime"

const channel = realtime.channel("room-123")

await channel.subscribe({
  events: ["chat.message"],
  history: true,
  onData({ event, data, channel }) {
    console.log("Message:", data)
  },
})
```

Pass history options:

```typescript route.ts
await channel.subscribe({
  events: ["chat.message"],
  history: {
    limit: 50,
    start: Date.now() - 3600000,
  },
  onData({ data }) {
    console.log("Message:", data)
  },
})
```

This pattern:

1. Fetches messages matching the history criteria
2. Replays them in chronological order
3. Continues to listen for new messages

## Use Cases

<AccordionGroup>
  <Accordion title="Background Jobs">
    Stream progress updates from long-running tasks:

```typescript app/api/job/route.ts
    import { realtime } from "@/lib/realtime"

export const POST = async (req: Request) => {
      const { jobId } = await req.json()
      const channel = realtime.channel(jobId)

await channel.emit("job.started", { progress: 0 })

for (let i = 0; i <= 100; i += 10) {
        await processChunk()
        await channel.emit("job.progress", { progress: i })
      }

await channel.emit("job.completed", { progress: 100 })

return new Response("OK")
    }
    ```

</Accordion>

<Accordion title="Event Processing">
    Process events with server-side logic:

```typescript route.ts
    import { realtime } from "@/lib/realtime"
    import { sendEmail } from "@/lib/email"

await realtime.channel("notifications").subscribe({
      events: ["notification.alert"],
      onData: async ({ data }) => {
        if (data.priority === "high") {
          await sendEmail({
            to: data.userId,
            subject: "Urgent Notification",
            body: data.message,
          })
        }
      },
    })
    ```

</Accordion>

<Accordion title="Multi-Channel Broadcasting">
    Emit events to multiple channels:

```typescript route.ts
    import { realtime } from "@/lib/realtime"

export const POST = async (req: Request) => {
      const { teamIds, message } = await req.json()

await Promise.all(
        teamIds.map((teamId: string) =>
          realtime.channel(`team-${teamId}`).emit("announcement", message)
        )
      )

return new Response("Broadcast sent")
    }
    ```

</Accordion>

<Accordion title="Webhook Processing">
    Forward webhook events to realtime channels:

```typescript app/api/webhook/route.ts
    import { realtime } from "@/lib/realtime"

export const POST = async (req: Request) => {
      const payload = await req.json()

const channel = realtime.channel(`user-${payload.userId}`)
      await channel.emit("webhook.received", payload)

return new Response("OK")
    }
    ```

</Accordion>
</AccordionGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="History" icon="clock-rotate-left" href="/realtime/features/history">
    Configure message retention and expiration
  </Card>

<Card title="Channels" icon="tower-broadcast" href="/realtime/features/channels">
    Scope events to specific rooms or users
  </Card>
</CardGroup>

# Deployment
Source: https://upstash.com/docs/realtime/features/serverless

<Note>
  Deploy Upstash Realtime to providers that bill **based on active CPU time**. Great places to
  deploy are
  * Vercel with Fluid Compute enabled
  * Cloudflare
  * Railway
  * A personal VPS
  * any other service that does not bill based on connection duration.
</Note>

## Deploying to Vercel

To deploy Upstash Realtime to Vercel, [enable Fluid Compute](https://vercel.com/docs/fluid-compute#enable-for-entire-project) for your project. For new projects, this is enabled by default.

Fluid Compute allows for less cold-starts, has much higher function timeouts compared to serverless functions, and most importantly **only bills for active CPU time**.

That way, you're only billed for actual message processing time, not connection duration.

<img />

## Optional: Configure Max Duration

You can configure the maximum duration for your realtime connections:

```typescript lib/realtime.ts
import { Realtime } from "@upstash/realtime"
import { redis } from "./redis"

export const realtime = new Realtime({
  schema,
  redis,
  maxDurationSecs: 300,
})
```

The default is 300 seconds (5 minutes), which works well with Vercel's Fluid Compute. After this interval, the client will automatically reconnect. Redis auto-replays all messages sent during reconnect.

## Billing Example

Traditional serverless connection billing:

```plaintext Serverless Billing
Connection duration: 5 minutes
Billing: 5 minutes = $$$
```

Upstash Realtime with fluid compute:

```plaintext Fluid Compute Billing
Connection duration: 5 minutes
Active processing: 2 seconds
Billing: 2 seconds x CPU cost = $
```

## Automatic Reconnection

The client automatically reconnects before your function timeout:

```tsx page.tsx
"use client"

import { useRealtime } from "@/lib/realtime-client"

export default function Component() {
  const { status } = useRealtime({
    events: ["notification.alert"],
    onData({ event, data, channel }) {},
  })

return <p>Status: {status}</p>
}
```

## Message Delivery Guarantee

Upstash Realtime is powered by Redis Streams, so no message is ever delivered twice or gets lost. Every message is guaranteed to be delivered exactly once.

1. Client establishes connection and subscribes to stream
2. Client initiates reconnection before function timeout (default every 5 mins)
3. Redis auto-replays all messages sent during reconnect

# Pricing
Source: https://upstash.com/docs/realtime/overall/pricing

**Upstash Realtime is designed to be extremely cost-efficient.** With minimal Redis commands per operation and smart connection management, you can build real-time features at scale without worrying about costs.

Upstash Realtime is built on Redis Streams and Pub/Sub. Every operation translates to one or more Redis commands, detailed below.

## Command Overview

### Client-Side Operations

When using [`useRealtime`](/docs/realtime/features/client-side#basic-usage) in your React components:

| Operation | Commands | Count |
| --------- | -------- | ----- |
| Initial connection | SUBSCRIBE, XRANGE | 2 |
| Reconnection every 300 seconds | UNSUBSCRIBE, XRANGE, SUBSCRIBE | 3 |
| Ping to keep connection alive every 60 seconds | PUBLISH | 1 |

### Server-Side Operations

When using the [server-side API](/docs/realtime/features/server-side):

| Operation | Commands | Count |
| --------- | -------- | ----- |
| [Emit event](/docs/realtime/features/server-side#emit-events) | PUBLISH, XADD | 2 |
| Emit with [`expireAfterSecs`](/docs/realtime/features/history#param-expire-after-secs) | PUBLISH, XADD, EXPIRE | 3 |
| [Read history](/docs/realtime/features/history#server-side-history) | XRANGE | 1 |

## Next Steps

<CardGroup cols={2}>
  <Card title="Client-Side Usage" icon="browser" href="/realtime/features/client-side">
    Learn how to use the useRealtime hook in React
  </Card>
  <Card title="History" icon="clock-rotate-left" href="/realtime/features/history">
    Learn how to read event history
  </Card>
</CardGroup>

# Quickstart
Source: https://upstash.com/docs/realtime/overall/quickstart

Upstash Realtime is the easiest way to add realtime features to any Next.js project.

## Why Upstash Realtime?

* 🧨 Clean APIs & first-class TypeScript support
* ⚡ Extremely fast, zero dependencies, 2.6kB gzipped
* 💻 Deploy anywhere: Vercel, Netlify, etc.
* 💎 100% type-safe with zod 4 or zod mini
* ⏱️ Built-in message histories
* 🔌 Automatic connection management w/ delivery guarantee
* 🔋 Built-in middleware and authentication helpers
* 📶 100% HTTP-based: Redis streams & SSE

***

## Quickstart

### 1. Installation

<CodeGroup>
```bash npm
npm install @upstash/realtime @upstash/redis zod
```

```bash yarn
yarn add @upstash/realtime @upstash/redis zod
```

```bash pnpm
pnpm add @upstash/realtime @upstash/redis zod
```

```bash bun
bun install @upstash/realtime @upstash/redis zod
```

</CodeGroup>

### 2. Configure Upstash Redis

Upstash Realtime is powered by Redis Streams. Grab your credentials from the [Upstash Console](https://console.upstash.com).

Add them to your environment variables:

```bash title=".env"
UPSTASH_REDIS_REST_URL=https://striking-osprey-20681.upstash.io
UPSTASH_REDIS_REST_TOKEN=AVDJAAIjcDEyZ...
```

And lastly, create a Redis instance:

```typescript title="lib/redis.ts"
import { Redis } from "@upstash/redis"

export const redis = new Redis({
  url: process.env.UPSTASH_REDIS_REST_URL,
  token: process.env.UPSTASH_REDIS_REST_TOKEN,
})
```

### 3. Define Event Schema

Define the structure of realtime events in your app:

```typescript title="lib/realtime.ts"
import { Realtime, InferRealtimeEvents } from "@upstash/realtime"
import { redis } from "./redis"
import z from "zod/v4"

const schema = {
  notification: {
    alert: z.string(),
  },
}

export const realtime = new Realtime({ schema, redis })
export type RealtimeEvents = InferRealtimeEvents<typeof realtime>
```

### 4. Create Realtime Route Handler

Create a route handler at `api/realtime/route.ts`:

```typescript title="app/api/realtime/route.ts"
import { handle } from "@upstash/realtime"
import { realtime } from "@/lib/realtime"

export const GET = handle({ realtime })
```

### 5. Add the Provider

Wrap your application in `RealtimeProvider`:

```tsx title="app/providers.tsx"
"use client"

import { RealtimeProvider } from "@upstash/realtime/client"

export function Providers({ children }: { children: React.ReactNode }) {
  return <RealtimeProvider>{children}</RealtimeProvider>
}
```

```tsx title="app/layout.tsx"
import { Providers } from "./providers"

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html>
      <body>
        <Providers>{children}</Providers>
      </body>
    </html>
  )
}
```

### 6. Create Typed Client Hook

Create a typed `useRealtime` hook for your client components:

```typescript title="lib/realtime-client.ts"
"use client"

import { createRealtime } from "@upstash/realtime/client"
import type { RealtimeEvents } from "./realtime"

export const { useRealtime } = createRealtime<RealtimeEvents>()
```

### 7. Emit Events

From any server component, server action, or API route:

```typescript title="app/api/notify/route.ts"
import { realtime } from "@/lib/realtime"

export const POST = async () => {
  await realtime.emit("notification.alert", "hello world!")

return new Response("OK")
}
```

### 8. Subscribe to Events

In any client component:

```tsx title="app/components/notifications.tsx"
"use client"

import { useRealtime } from "@/lib/realtime-client"

export default function Notifications() {
  useRealtime({
    events: ["notification.alert"],
    onData({ event, data, channel }) {
      console.log(`Received ${event}:`, data)
    },
  })

return <p>Listening for events...</p>
}
```

That's it! Your app is now listening for realtime events with full type safety. 🎉

### 9. Realtime Dashboard

For debugging or monitoring purposes, you can use Realtime Dashboard in console.

<img />

## Next Steps

<CardGroup cols={2}>
  <Card title="Client-Side Usage" icon="react" href="/realtime/features/client-side">
    Complete guide to the useRealtime hook
  </Card>

<Card title="Server-Side Usage" icon="server" href="/realtime/features/server-side">
    Subscribe to events and stream updates on the server
  </Card>

<Card title="Channels" icon="tower-broadcast" href="/realtime/features/channels">
    Scope events to specific rooms or channels
  </Card>

<Card title="History" icon="clock-rotate-left" href="/realtime/features/history">
    Fetch and replay past messages
  </Card>
</CardGroup>

# Examples Index
Source: https://upstash.com/docs/redis/examples

TODO: fahreddin
import TagFilters from "../../src/components/Filter.js"

<TagFilters>
  <TagFilters.Item
    externalLink
    type="Article"
    tags={["Svelte"]}
    url="https://blog.upstash.com/sveltekit-todo-redis"
  >
    SvelteKit TODO App with Redis
  </TagFilters.Item>
  <TagFilters.Item
    externalLink
    type="Article"
    tags={["Strapi"]}
    url="https://blog.upstash.com/redis-strapi"
  >
    Serverless Redis Caching for Strapi
  </TagFilters.Item>
  <TagFilters.Item
    externalLink
    type="Article"
    tags={["Blitz.js"]}
    url="https://blog.upstash.com/blitzjs-todo-redis"
  >
    To-Do List with Blitz.js & Redis
  </TagFilters.Item>
  <TagFilters.Item
    externalLink
    type="Article"
    tags={["AWS Chalice", "Slackbot"]}
    url="https://blog.upstash.com/chalice-event-reminder-slackbot"
  >
    Slackbot with AWS Chalice and Upstash Redis
  </TagFilters.Item>
  <TagFilters.Item
    externalLink
    type="Article"
    tags={["Render"]}
    url="https://blog.upstash.com/render-serverless-redis"
  >
    Using Render with Redis
  </TagFilters.Item>
  <TagFilters.Item
    externalLink
    type="Article"
    tags={["Slackbot", "Vercel"]}
    url="https://blog.upstash.com/vercel-note-taker-slackbot"
  >
    Slackbot with Vercel and Upstash Redis
  </TagFilters.Item>
  <TagFilters.Item
    externalLink
    type="Article"
    tags={["Slackbot", "Vercel"]}
    url="https://blog.upstash.com/vercel-note-taker-slackbot"
  >
    Slackbot with Vercel and Upstash Redis
  </TagFilters.Item>
  <TagFilters.Item
    externalLink
    type="Article"
    tags={["Remix", "Cloudflare Workers"]}
    url="https://blog.upstash.com/fast_websites_with_Remix_on_Cloudflare_and_Upstash_Redis"
  >
    Remix on Cloudflare with Upstash Redis
  </TagFilters.Item>
  <TagFilters.Item
    externalLink
    type="Article"
    tags={["Remix"]}
    url="https://blog.upstash.com/remix-todo-redis"
  >
    Remix TODO App with Redis
  </TagFilters.Item>
  <TagFilters.Item
    externalLink
    type="Article"
    tags={["GraphQL", "Netlify"]}
    url="https://blog.upstash.com/netlify-graph-upstash"
  >
    Global Cache for Netlify Graph with Upstash Redis
  </TagFilters.Item>
  <TagFilters.Item
    externalLink
    type="Article"
    tags={["Next.js", "NextAuth"]}
    url="https://blog.upstash.com/next-auth-serverless-redis"
  >
    Next.js Authentication with NextAuth and Serverless Redis
  </TagFilters.Item>
  <TagFilters.Item
    externalLink
    type="Article"
    tags={["Next.js"]}
    url="https://blog.upstash.com/survey-serverless-redis"
  >
    Building a Survey App with Upstash Redis and Next.js
  </TagFilters.Item>
  <TagFilters.Item
    externalLink
    type="Article"
    tags={["React Native", "Mobile"]}
    url="https://blog.upstash.com/serverless-react-native"
  >
    Building React Native Apps Backed by AWS Lambda and Serverless Redis
  </TagFilters.Item>
  <TagFilters.Item
    externalLink
    type="Article"
    tags={["Remix", "Node.js"]}
    url="https://blog.upstash.com/redis-with-remix"
  >
    Using Upstash Redis with Remix
  </TagFilters.Item>
  <TagFilters.Item
    externalLink
    type="Article"
    tags={["Remix", "Node.js"]}
    url="https://blog.upstash.com/redis-session-remix"
  >
    Using Upstash Redis as a Session Store for Remix
  </TagFilters.Item>
  <TagFilters.Item
    externalLink
    type="Article"
    tags={["REST-API", "Backendless"]}
    url="https://docs.upstash.com/redis/tutorials/notification"
  >
    Building a Serverless Notification API for Your Web Application with Redis
  </TagFilters.Item>
  <TagFilters.Item
    externalLink
    type="Article"
    tags={["AWS App Runner", "Node.js"]}
    url="https://docs.upstash.com/redis/tutorials/aws_app_runner_with_redis"
  >
    Build Stateful Applications with AWS App Runner and Serverless Redis
  </TagFilters.Item>
  <TagFilters.Item
    externalLink
    type="Article"
    tags={["Google Cloud"]}
    url="https://docs.upstash.com/redis/tutorials/cloud_run_sessions"
  >
    Session Management on Google Cloud Run with Serverless Redis
  </TagFilters.Item>
  <TagFilters.Item
    externalLink
    type="Article"
    tags={["Cloudflare Workers", "upstash-redis", "REST-API"]}
    url="https://docs.upstash.com/redis/tutorials/cloudflare_workers_with_redis"
  >
    Use Redis in Cloudflare Workers
  </TagFilters.Item>
  <TagFilters.Item
    externalLink
    type="Article"
    tags={["Fastly Compute", "upstash-redis", "REST-API"]}
    url="https://blog.upstash.com/fastly-compute-edge-with-redis"
  >
    Use Redis in Fastly Compute
  </TagFilters.Item>
  <TagFilters.Item
    externalLink
    type="Article"
    tags={["Cloudflare Workers"]}
    url="https://docs.upstash.com/redis/tutorials/edge_leaderboard"
  >
    Build a Leaderboard API at Edge Using Cloudflare Workers and Redis
  </TagFilters.Item>
  <TagFilters.Item
    externalLink
    type="Article"
    tags={["AWS Lambda", "Node.js"]}
    url="https://docs.upstash.com/redis/tutorials/job_processing"
  >
    Job Processing and Event Queue with Serverless Redis
  </TagFilters.Item>
  <TagFilters.Item
    externalLink
    type="Article"
    tags={["AWS Lambda", "Node.js"]}
    url="https://docs.upstash.com/redis/tutorials/rate-limiting"
  >
    AWS Lambda Rate Limiting with Serverless Redis
  </TagFilters.Item>
  <TagFilters.Item
    externalLink
    type="Article"
    tags={["AWS Lambda", "Node.js"]}
    url="https://docs.upstash.com/redis/tutorials/histogram"
  >
    Build a Serverless Histogram API with Redis
  </TagFilters.Item>
  <TagFilters.Item
    externalLink
    type="Article"
    tags={["AWS Lambda", "Node.js"]}
    url="https://docs.upstash.com/redis/tutorials/auto_complete_with_serverless_redis"
  >
    Autocomplete API with Serverless Redis
  </TagFilters.Item>
  <TagFilters.Item
    externalLink
    type="Article"
    tags={["Next.js", "Vercel"]}
    url="https://docs.upstash.com/redis/tutorials/roadmapvotingapp"
  >
    Roadmap Voting App with Serverless Redis
  </TagFilters.Item>
  <TagFilters.Item
    externalLink
    type="Article"
    tags={["Next.js"]}
    url="https://blog.upstash.com/survey-serverless-redis"
  >
    Building a Survey App with Upstash Redis only
  </TagFilters.Item>
  <TagFilters.Item
    externalLink
    type="Article"
    tags={["Google Cloud"]}
    url="https://docs.upstash.com/redis/tutorials/using_google_cloud_functions"
  >
    Serverless Redis on Google Cloud Functions
  </TagFilters.Item>
  <TagFilters.Item
    externalLink
    type="Article"
    tags={["AWS Lambda"]}
    url="https://docs.upstash.com/redis/tutorials/using_serverless_framework"
  >
    Using Serverless Framework
  </TagFilters.Item>
  <TagFilters.Item
    externalLink
    type="Article"
    tags={["AWS Lambda"]}
    url="https://docs.upstash.com/redis/tutorials/using_aws_sam"
  >
    Using AWS SAM
  </TagFilters.Item>
  <TagFilters.Item
    externalLink
    type="Article"
    tags={["AWS Lambda"]}
    url="https://docs.upstash.com/redis/tutorials/api_with_cdk"
  >
    Deploy a Serverless API with AWS CDK and AWS Lambda
  </TagFilters.Item>
  <TagFilters.Item
    externalLink
    type="Article"
    tags={["Node.js"]}
    url="https://docs.upstash.com/redis/tutorials/express_session"
  >
    Express Session with Serverless Redis
  </TagFilters.Item>
  <TagFilters.Item
    externalLink
    type="Article"
    tags={["Next.js"]}
    url="https://docs.upstash.com/redis/tutorials/nextjs_with_redis"
  >
    Next.js with Redis
  </TagFilters.Item>
  <TagFilters.Item
    externalLink
    type="Article"
    tags={["Nuxt.js"]}
    url="https://docs.upstash.com/redis/tutorials/nuxtjs_with_redis"
  >
    Nuxt.js with Redis
  </TagFilters.Item>
  <TagFilters.Item
    externalLink
    type="Article"
    tags={["Java", "AWS Lambda"]}
    url="https://docs.upstash.com/redis/tutorials/serverless_java_redis"
  >
    Serverless API with Java and Redis
  </TagFilters.Item>
  <TagFilters.Item
    externalLink
    type="Article"
    tags={["Go", "AWS Lambda"]}
    url="https://docs.upstash.com/redis/tutorials/goapi"
  >
    Serverless Golang API with Redis
  </TagFilters.Item>
  <TagFilters.Item
    externalLink
    type="Article"
    tags={["Python", "AWS Lambda"]}
    url="https://docs.upstash.com/redis/tutorials/pythonapi"
  >
    Serverless Python API with Redis
  </TagFilters.Item>
  <TagFilters.Item
    externalLink
    type="Article"
    tags={["Java"]}
    url="https://docs.upstash.com/redis/tutorials/redisson"
  >
    Serverless Redisson
  </TagFilters.Item>
  <TagFilters.Item
    externalLink
    type="Article"
    tags={["Svelte", "Netlify"]}
    url="https://blog.upstash.com/svelte-with-serverless-redis"
  >
    Building SvelteKit Applications with Serverless Redis
  </TagFilters.Item>
  <TagFilters.Item
    externalLink
    type="Article"
    tags={["Cloudflare Workers", "upstash-redis", "REST-API"]}
    url="https://blog.upstash.com/cloudflare-workers-waiting-room"
  >
    Build Your Own Waiting Room for Your Website with Cloudflare Workers and
    Serverless Redis
  </TagFilters.Item>
  <TagFilters.Item
    externalLink
    type="Article"
    tags={["AWS Lambda", "Mobile", "Flutter"]}
    url="https://blog.upstash.com/serverless-with-flutter"
  >
    Fullstack Serverless App with Flutter, Serverless Framework and
    Upstash(REDIS) - PART 1
  </TagFilters.Item>
  <TagFilters.Item
    externalLink
    type="Article"
    tags={["Next.js Edge", "Next.js", "Vercel"]}
    url="https://blog.upstash.com/getstarted-nextjs-edge-with-redis"
  >
    Getting Started with Next.js Edge Functions
  </TagFilters.Item>
  <TagFilters.Item
    externalLink
    type="Article"
    tags={["Next.js Edge", "Next.js", "Vercel"]}
    url="https://blog.upstash.com/nextjs-edge-waiting-room"
  >
    Waiting Room for Your Next.js App Using Edge Functions
  </TagFilters.Item>
  <TagFilters.Item
    externalLink
    type="Article"
    tags={["Benchmark"]}
    url="https://blog.upstash.com/serverless-database-benchmark"
  >
    Serverless Battleground - DynamoDB vs Firestore vs MongoDB vs Cassandra vs
    Redis vs FaunaDB
  </TagFilters.Item>
  <TagFilters.Item
    externalLink
    type="Article"
    tags={["AWS Lambda", "REST-API"]}
    url="https://blog.upstash.com/aws-lambda-redis-rest"
  >
    Stateful AWS Lambda with Redis REST
  </TagFilters.Item>
  <TagFilters.Item
    externalLink
    type="Article"
    tags={["REST-API"]}
    url="https://blog.upstash.com/pipeline"
  >
    Pipeline REST API on Serverless Redis
  </TagFilters.Item>
  <TagFilters.Item
    externalLink
    type="Article"
    tags={["Next.js", "Vercel", "REST-API"]}
    url="https://blog.upstash.com/nextjs-todo"
  >
    The Most Minimalist Next.js TODO App
  </TagFilters.Item>
  <TagFilters.Item
    externalLink
    type="Article"
    tags={["Cloudflare Workers", "REST-API"]}
    url="https://blog.upstash.com/edge-guard"
  >
    Implement IP Allow/Deny List at Edge with Cloudflare Workers and Upstash
    Redis
  </TagFilters.Item>
  <TagFilters.Item
    externalLink
    type="Article"
    tags={["Cloudflare Workers"]}
    url="https://blog.upstash.com/redis-cloudflare-workers"
  >
    Redis @ Edge with Cloudflare Workers
  </TagFilters.Item>
  <TagFilters.Item
    externalLink
    type="Video"
    tags={["Next.js", "Vercel"]}
    url="https://www.youtube.com/watch?v=FytxaSVQROc"
  >
    Using Serverless Redis with Next.js
  </TagFilters.Item>
  <TagFilters.Item
    externalLink
    type="Video"
    tags={["Next.js"]}
    url="https://www.youtube.com/watch?v=sBiUqozxY4o"
  >
    Building a Cache with Upstash Redis in Next.js
  </TagFilters.Item>
  <TagFilters.Item
    externalLink
    type="Video"
    tags={["Next.js Edge", "Next.js", "Vercel"]}
    url="https://www.youtube.com/watch?v=hu2SrILiEgE"
  >
    Vercel Edge Function URL Shortener with Upstash Redis
  </TagFilters.Item>
  <TagFilters.Item
    externalLink
    type="Video"
    tags={["Next.js"]}
    url="https://www.youtube.com/watch?v=S1oOlKQo8CY"
  >
    Adding Feature Flags to Next.js (Upstash Redis, SWR, Hooks)
  </TagFilters.Item>
  <TagFilters.Item
    externalLink
    type="Video"
    tags={["Next.js"]}
    url="https://www.youtube.com/watch?v=_opoQpUMqF4"
  >
    Rate Limiting Your Serverless Functions with Upstash Redis
  </TagFilters.Item>
  <TagFilters.Item
    externalLink
    type="Video"
    tags={["Next.js"]}
    url="https://www.youtube.com/watch?v=1Dotv9T7nIs"
  >
    Create a React Scoreboard with Upstash Redis
  </TagFilters.Item>
  <TagFilters.Item
    externalLink
    type="Video"
    tags={["Go", "AWS Lambda"]}
    url="https://www.youtube.com/watch?v=EJ6CJ0GC9lk"
  >
    Upstash on AWS Lambda Using Golang
  </TagFilters.Item>
  <TagFilters.Item
    externalLink
    type="Video"
    tags={["Cloudflare Workers"]}
    url="https://www.youtube.com/watch?v=g6hGJcuscoM"
  >
    IP Address Allow/Deny with Cloudflare Workers and Upstash Redis
  </TagFilters.Item>
  <TagFilters.Item
    externalLink
    type="Video"
    tags={["Vercel", "Next.js Edge"]}
    url="https://www.youtube.com/watch?v=yuxd2kurpzk&t=968s"
  >
    Edge Functions Explained with Kelsey Hightower and Lee Robinson - (Next.js
    Conf 2021)
  </TagFilters.Item>
  <TagFilters.Item
    externalLink
    type="Article"
    tags={["Elixir"]}
    url="https://docs.upstash.com/redis/tutorials/elixir_with_redis"
  >
    Elixir with Redis
  </TagFilters.Item>
</TagFilters>

# Auto Upgrade
Source: https://upstash.com/docs/redis/features/auto-upgrade

By default, Upstash will apply usage limits based on your current plan. When you reach these limits, behavior depends on the specific limit type - bandwidth limits will throttle your traffic, while storage limits will reject new write operations. However, Upstash offers an Auto Upgrade feature that automatically upgrades your database to the next higher plan when you reach your usage limits, ensuring uninterrupted service.

Auto Upgrade is particularly useful for applications with fluctuating or growing workloads, as it prevents service disruptions during high-traffic periods or when your data storage needs expand beyond your current plan. This feature allows your database to automatically scale with your application's demands without requiring manual intervention.

## How Auto Upgrade Works

When enabled:

* For **bandwidth limits**: Instead of throttling your traffic when you reach the bandwidth limit, your database will automatically upgrade to the next plan to accommodate the increased traffic.
* For **storage limits**:
    * **When eviction is off**: Instead of rejecting write operations when you reach maximum data size, your database will upgrade to a plan with larger storage capacity.
    * **When eviction is on**: Your data will be evicted and operations will resume. Auto Upgrade will not be triggered and system will rely on eviction mechanism in this case.

## Managing Auto Upgrade

* You can enable Auto Upgrade by checking the Auto Upgrade checkbox while creating a new database:

* Or for an existing database by clicking Enable in the Configuration/Auto Upgrade box in the database details page:
    <img width="600" height="300" />

# Backup/Restore
Source: https://upstash.com/docs/redis/features/backup

You can create backups of your Redis database and restore them when needed. Backups allow you to preserve your data and recover it to any database in your account or team.

## Creating a Backup

<Info>
  During a backup operation, certain administrative operations will be temporarily unavailable: Backup operations, database config changes, plan and region setup, transferring database.
  Regular Redis commands (GET, SET, etc.) are not blocked and continue to work normally.
</Info>

There are two ways to create a backup of your database:

### Create an Immediate Backup

To create a backup right now:

* Go to the database details page and navigate to the `Backups` tab
* Click on the `Backup & Export` button
* Choose `Backup`

Backup process will start and will appear in the backups table below.

### Schedule Periodic Backups

To automatically create backups on a regular schedule:

* Go to the database details page and navigate to the `Backups` tab
* Click the switch next to `Daily Backup` to enable daily backup or click on `Daily Backup` text itself to select how long the backup is to be stored (1 or 3 days)

With daily backups enabled, your database will be automatically backed up every day.

### Managing Backups

All created backups are displayed in the backups table in the `Backups` tab. From this table, you can:

* View backup details (name, creation date, size)
* Restore your database from any backup
* Delete backups you no longer need

## Restoring from Backup

<Warning>
  All existing data in the target database will be deleted before the restore operation begins.
</Warning>

You can restore your database from any backup in your account or team.

### Restore from the Backups Table

To restore from a backup of the current database:

* Go to the database details page and navigate to the `Backups` tab
* Find the backup you want to restore in the backups table
* Click on the `Restore` button next to the backup
* Confirm that you are deleting existing data and want to proceed with the restore

### Restore from Any Database Backup

To restore from a backup created from any database in your account or team:

* Go to the database details page and navigate to the `Backups` tab
* Click on the `Restore...` button
* Select the source database (the database from which the backup was created)
* Select the backup you want to restore
* Click on `Start Restore`

### Restore from the Redis List Page

You can also restore databases directly from the Redis list page. This method is explained in detail in the [Import/Export documentation](/docs/redis/howto/importexport).

# 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](/docs/redis/howto/readyourwrites) for more details on how to achieve RYW consistency.

Checkout [Replication](/docs/redis/features/replication) for more details on Replication mechanism.

<Note>
  Previously, Upstash supported `Strong Consistency` mode for the single region
  databases. We decided to deprecate this feature because its effect on latency
  started to conflict with the performance expectations of Redis use cases. Also
  we are gradually moving to **CRDT** based Redis data structures, which will
  provide `Strong Eventual Consistency`.
</Note>

# Credential Protection
Source: https://upstash.com/docs/redis/features/credential-protection

Enabling Credential Protection ensures your database credentials are never stored within Upstash infrastructure. This enhances security by making credentials accessible only once—at the moment they are generated.

<Note>
  Credential Protection is a [Production
  Pack](/docs/redis/overall/enterprise#prod-pack-features)
  feature.
</Note>

## How It Works

When enabled:

* Redis database credentials are no longer stored in Upstash infrastructure
* Credentials are displayed only once during enablement - save them immediately
* Console features requiring database access are disabled (CLI, Data Browser, Monitor, ACL)

## Managing Credential Protection

1. Go to database details page → Configuration section
2. Toggle **Protect Credentials** switch:

<img />

3. Save the credentials shown in the modal:

<img />

<Warning>
  Disabling this feature will permanently revoke current credentials and
  generate new ones, potentially breaking applications using those credentials.
</Warning>

## What If You Lose Your Credentials

**Reset Credentials**: This function remains available and, when credential protection is enabled, will generate new protected credentials.

<img />

# Durable Storage
Source: https://upstash.com/docs/redis/features/durability

In Upstash, persistence is always enabled, setting it apart from other Redis
offerings. Every write operation is consistently stored in both memory and the
block storage provided by cloud providers, such as AWS's EBS. This dual storage
approach ensures data durability. Read operations are optimized to first check
if the data exists in memory, facilitating faster access. If the data is not in
memory, it is retrieved from disk. This combination of memory and disk storage
in Upstash guarantees reliable data access and maintains data integrity, even
during system restarts or failures.

### Multi Tier Storage

Upstash keeps your data both in memory and disk. This design provides:

* Data safety with persistent storage
* Low latency with in memory access
* Price flexibility by using memory only for active data

In Upstash, an entry in memory is evicted if it remains idle, meaning it has not
been accessed for an extended period. It's important to note that eviction does
not result in data loss since the entry is still stored in the block storage.
When a read operation occurs for an evicted entry, it is efficiently reloaded
from the block storage back into memory, ensuring fast access to the data. This
eviction mechanism in Upstash optimizes memory usage by prioritizing frequently
accessed data while maintaining the ability to retrieve less frequently accessed
data when needed.

<Card
  title="Can I use Upstash as a database?"
  icon="lightbulb"
  iconType="duotone"
  color="#34D399"
>
  Definitely, yes. Some users are worried that Redis data will be lost when a
  server crashes. This is not the case for Upstash thanks to Durable Storage.
  Data is reloaded to memory from block storage in case of a server crash.
  Moreover, except for the free tier, all paid tier databases provide extra redundancy by replicating data to multiple instances.
</Card>

# Eviction
Source: https://upstash.com/docs/redis/features/eviction

By default eviction is disabled, and Upstash Redis will reject write operations once the maximum data size
limit has been reached. However, if you are utilizing Upstash Redis as a cache, you
have the option to enable eviction. Enabling eviction allows older data to be
automatically removed from the cache (including Durable Storage) when the maximum size limit is reached.
This ensures that the cache remains within the allocated size and can make room
for new data to be stored. Enabling eviction is particularly useful when the
cache is intended to store frequently changing or temporary data, allowing the
cache to adapt to evolving data needs while maintaining optimal performance.

* You can enable eviction by checking **Eviction** checkbox while creating a new
  database:

<img />

* Or for an existing database by clicking **Enable** in Configuration/Eviction
  box in the database details page:
    <img />

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/latest/operate/rs/databases/memory-performance/eviction-policy/).

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

<Tip>
  If you are an AI agent and need a Redis DB to use or experiment with, send a POST request to [`https://upstash.com/start-redis`](https://upstash.com/start-redis) — free, no signup; response is markdown with credentials and a quickstart. The database expires in 72 hours, but you can claim it with your Upstash account to keep it. Especially useful for AI agents that need scratch storage on the fly.
</Tip>

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, which can be initiated from any region, 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:

<Tabs>

| Region | Code |
|--------|------|
| N. Virginia, USA | us-east-1 |
| Ohio, USA | us-east-2 |
| N. California, USA | us-west-1 |
| Oregon, USA | us-west-2 |
| Central Canada | ca-central-1 |
| Sao Paulo, Brazil | sa-east-1 |
| Ireland | eu-west-1 |
| London, UK | eu-west-2 |
| Frankfurt, Germany | eu-central-1 |
| Mumbai, India | ap-south-1 |
| Singapore | ap-southeast-1 |
| Tokyo, Japan | ap-northeast-1 |
| Sydney, Australia | ap-southeast-2 |
| Cape Town, South Africa | af-south-1 |

</Tab>

| Region | Code |
|--------|------|
| Iowa, USA | us-central1 |
| Virginia, USA | us-east4 |
| Belgium | europe-west1 |
| Tokyo, Japan | asia-northeast1 |

</Tab>

</Tabs>

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.

<Note>
  Global Database is designed to optimize the latency of READ operations. It may
  not be a good choice if your use case is WRITE heavy.
</Note>

### Use Cases

* **Edge functions:** Edge computing (Cloudflare workers, Fastly Compute) is
  becoming a popular way of building globally fast applications. But there are
  limited data solutions accessible from edge functions. Upstash Global Database
  is accessible from Edge functions with the REST API. Low latency from all edge
  locations makes it a perfect solution for Edge functions

* Multi region serverless architectures: You can run your AWS Lambda function in
  multiple regions to lower global latency. Vercel/Netlify functions can be run
  in different regions. Upstash Global database provides low latency data
  wherever your serverless functions are.

* Web/mobile use cases where you need low latency globally. Thanks to the read
  only REST API, you can access Redis from your web/mobile application directly.
  In such a case, Global Database will help to lower the latency as you can
  expect the clients from anywhere.

### High Availability and Disaster Recovery

Although the main motivation behind the Global Database is to provide low
latency; it also makes your database resilient to region wide failures. When a
region is not available, your requests are routed to another region; so your
database remains available.

### Consistency

Global Database is an eventually consistent database. The write request returns
after the primary replica processes the operation. Write operation is replicated
to read replicas asynchronously. Read requests can be served by any replica,
which gives better horizontal scalability but also means a read request may
return a stale value while a write operation for the same key is being
propagated to read replicas.

In case of cluster wide failures like network partitioning (split brain);
periodically running anti entropy jobs resolve the conflicts using LWW
algorithms and converge the replicas to the same state.

### Upgrade from Regional to Global

Currently, we do not support auto-upgrade from regional to global database. You
can export data from your old database and import into the global database.

### Pricing

Global Database charges \$0.2 per 100K commands. The write commands are replicated to all read regions in addition to primary region so the replications are counted as commands. For example, if you have 1 primary 1 read region, 100K writes will cost \$0.4 (\$0.2 x 2). You can use Global Database in the free tier too. Free usage is limited with max one read region.

# Key-Based Locking
Source: https://upstash.com/docs/redis/features/key-locking

Upstash Redis databases use locks to keep commands isolated while allowing
independent keys to be processed in parallel. The engine automatically locks
the keys used by the command. Commands that operate on different keys can run
concurrently, subject to the parallelism available to your database.

Key-based locking is transparent to clients. You do not need to change regular
Redis commands to use it.

## How It Works

* Single-key commands (for example `GET`, `SET`, `INCR`, `HSET`) acquire a
  lock on just that key.
* Multi-key commands acquire locks on every key they reference, in a
  deterministic order to avoid deadlocks.
* Read-only commands (for example `GET`, `HGET`, `LRANGE`) take a shared read
  lock, so multiple readers on the same key run concurrently. Read
  locks block writers on that key until they complete.
* Commands that need a database-wide operation, such as `FLUSHDB` and
  `FLUSHALL`, take the global lock and can reduce concurrency while they run.

## Transactions

Transactions (`MULTI`/`EXEC`) use key-based locking at `EXEC` time. While
commands are queued, Upstash collects the keys referenced by the transaction.
When `EXEC` runs, the engine takes an exclusive write lock for the union of
those keys and executes the queued commands atomically.

Transactions that touch disjoint key sets can run concurrently. Transactions
that share any key block each other until one transaction finishes.

```redis
MULTI
SET user:42:name "Ada"
INCR user:42:version
EXEC
```

In this example, `EXEC` locks `user:42:name` and `user:42:version` for the
duration of the transaction.

If a queued command requires a database-wide lock, the whole transaction uses
the global lock. This includes commands such as `FLUSHDB` and `FLUSHALL`.

Lua scripts queued inside a transaction always execute under the global lock,
even if the script declares [`allow-key-locking`](#lua-scripts). If you want
script-level key locking, run the script directly with `EVAL`/`EVALSHA`
outside of a transaction.

## Lua Scripts

Lua scripts (`EVAL`, `EVALSHA`, `EVAL_RO`, `EVALSHA_RO`) default to the global
lock because the engine cannot know in advance which keys the script will use.
To opt into key-based locking, add the `allow-key-locking` flag to the script's
shebang line:

```lua
#!lua flags=allow-key-locking

redis.call('INCR', KEYS[1])
redis.call('INCRBY', KEYS[2], ARGV[1])
return "OK"
```

When the flag is set, Upstash locks only the keys passed through the `KEYS`
array when the script is invoked. Other commands and scripts that touch disjoint
keys can run in parallel.

### Rules for `allow-key-locking`

* **Every key passed to `redis.call` must appear in `KEYS`.** You may compute
  the key value inside the script (for example by concatenating parts of
  `ARGV`), but the final string must exactly match one of the entries declared
  in the `KEYS` array. Otherwise the engine rejects the command:

```
  ERR Dynamic keys are not allowed in Lua scripts when 'allow-key-locking' flag is set. Key was: <key>
  ```

In practice, this means you should pass fully resolved keys through `KEYS`
  rather than reconstructing them from `ARGV` inside the script.

* **Database-wide writes are not allowed.** Commands that require database-wide
  exclusive access, such as `FLUSHDB` and `FLUSHALL`, cannot be called from a
  script with `allow-key-locking`. Run those scripts without the flag so the
  engine can use the global lock.

Read-only script variants and scripts with the `no-writes` flag also need
`allow-key-locking` if you want them to use per-key read locks. Without it, they
run under the global lock. To use both flags in a Lua script, separate them with
a comma:

```lua
#!lua flags=no-writes,allow-key-locking
```

### When to use it

Enable `allow-key-locking` for short scripts that operate on a small, known
set of keys and are called frequently enough that the global lock becomes a
bottleneck (for example counters, rate limiters, or per-user state
transitions). For scripts that must scan or mutate many keys at once, leave
the flag off so the engine uses the global lock.

### Example: Key-Locked Counter

```lua
#!lua flags=allow-key-locking

local current = tonumber(redis.call('GET', KEYS[1]) or "0")
if current >= tonumber(ARGV[1]) then
  return 0
end
redis.call('INCR', KEYS[1])
return 1
```

Invoked with:

```
EVAL "<script>" 1 user:42:quota 100
```

Multiple clients calling this script for different users will execute
concurrently, each holding a lock only on its own `user:<id>:quota` key.

## Redis Functions

Redis functions (`FCALL`, `FCALL_RO`) also default to the global lock. For
functions, `allow-key-locking` is set on each registered function, not on the
library shebang:

```lua
#!lua name=locks

local function incr_if_below(keys, args)
  local current = tonumber(redis.call('GET', keys[1]) or "0")
  if current >= tonumber(args[1]) then
    return 0
  end

redis.call('INCR', keys[1])
  return 1
end

redis.register_function{
  function_name='incr_if_below',
  callback=incr_if_below,
  flags={'allow-key-locking'}
}
```

Invoked with:

```
FCALL incr_if_below 1 user:42:quota 100
```

The same rules apply: every key used by the function must be passed in the
`FCALL` key list. Keys passed as regular arguments are not locked unless they
also appear in the key list.

If the function is also read-only, include both flags in the function
registration:

```lua
flags={'no-writes', 'allow-key-locking'}
```

# Replication
Source: https://upstash.com/docs/redis/features/replication

Replication is enabled for all paid Upstash databases. The data is replicated to
multiple instances. Replication provides you high availability and better
scalability.

### High Availability

Replication makes your database resilient to failures because even one of the
replicas is not available, your database continues to work.

There are two types of replicas in Upstash Redis: primary replicas and read replicas. Primary replicas handle both reads and writes, while read replicas are used only for reads.

In all subscription plans, primary replicas are highly available with multiple replicas to ensure that even if one fails, your database continues to function.

If a read replica fails, your database remains operational, and you can still read from the primary replicas, though with higher latency.
When [Prod Pack](/docs/redis/overall/enterprise#prod-pack-features) is enabled, replicas (including read replicas) are deployed across multiple availability zones. This gives regions multi-zone high availability: if one replica or zone fails, another replica in a different zone continues serving commands in the same region without any additional latency.

### Better Scalability

In a replicated database, your requests are evenly distributed among the
replicas using a round-robin approach. As your throughput requirements grow,
additional replicas can be added to the cluster to handle the increased workload
and maintain high performance. This scalability feature ensures that your
database can effectively meet the demands of high throughput scenarios.

### Architecture

We use the single leader replication model. Each key is owned by a leader
replica and other replicas become the backups of the leader. Writes on a key are
processed by the leader replica first then propagated to backup replicas. Reads
can be performed from any replica. This model gives a better write consistency
and read scalability.

### Consistency

Each replica in the cluster utilizes a failure detector to monitor the status of
the leader replica. In the event that the leader replica fails, the remaining
replicas initiate a new leader election process to select a new leader. During
this leader election round, which is the only unavailability window for the
cluster, there may be a short period of time where your requests can be
temporarily blocked.

However, once a new leader is elected, normal operations resume, ensuring the
continued availability of the cluster. This mechanism ensures that any potential
unavailability caused by leader failure is minimized, and the cluster can
quickly recover and resume processing requests.

Checkout [Read Your Writes](/docs/redis/howto/readyourwrites) for more details on how to achieve RYW consistency.

# REST API
Source: https://upstash.com/docs/redis/features/restapi

REST API enables you to access your Upstash database using REST.

## Get Started

If you do not have a database already, follow
[these steps](../overall/getstarted) to create one.

In the [Upstash Console](https://console.upstash.com/redis), select your database. Then, in the database page, you will see the section that includes the endpoint URL and token details. When you hover over the `Endpoint` or `Token / Readonly Token` fields, copy button will appear for each. You can click it to easily copy the values you need for your connection.

Copy the `HTTPS` for REST URL and the `Token` for authorization. Send an HTTP SET request to the
provided URL by adding an `Authorization: Bearer $TOKEN` header like below: (See the sample command with your credentials in the `cURL` tab of Connection section)

```shell
curl https://us1-merry-cat-32748.upstash.io/set/foo/bar \
 -H "Authorization: Bearer 2553feg6a2d9842h2a0gcdb5f8efe9934"
```

The above script executes a `SET foo bar` command. It will return a JSON
response:

```json
{ "result": "OK" }
```

You can also set the token as `_token` request parameter as below:

```shell
curl https://us1-merry-cat-32748.upstash.io/set/foo/bar?_token=2553feg6a2d9842h2a0gcdb5f8efe9934
```

## API Semantics

Upstash REST API follows the same convention with
[Redis Protocol](https://redis.io/commands). Give the command name and
parameters in the same order as Redis protocol by separating them with a `/`.

```shell
curl REST_URL/COMMAND/arg1/arg2/../argN
```

Here are some examples:

* `SET foo bar` -> `REST_URL/set/foo/bar`

* `SET foo bar EX 100` -> `REST_URL/set/foo/bar/EX/100`

* `GET foo` -> `REST_URL/get/foo`

* `MGET foo1 foo2 foo3` -> `REST_URL/mget/foo1/foo2/foo3`

* `HGET employee:23381 salary` -> `REST_URL/hget/employee:23381/salary`

* `ZADD teams 100 team-x 90 team-y` ->
  `REST_URL/zadd/teams/100/team-x/90/team-y`

#### JSON or Binary Value

To post a JSON or a binary value, you can use an HTTP POST request and set value
as the request body:

```shell
curl -X POST -d '$VALUE' https://us1-merry-cat-32748.upstash.io/set/foo \
 -H "Authorization: Bearer 2553feg6a2d9842h2a0gcdb5f8efe9934"
```

In the example above, `$VALUE` sent in request body is appended to the command
as `REST_URL/set/foo/$VALUE`.

Please note that when making a POST request to the Upstash REST API, the request
body is appended as the last parameter of the Redis command. If there are
additional parameters in the Redis command after the value, you should include
them as query parameters in the request:

```shell
curl -X POST -d '$VALUE' https://us1-merry-cat-32748.upstash.io/set/foo?EX=100 \
 -H "Authorization: Bearer 2553feg6a2d9842h2a0gcdb5f8efe9934"
```

Above command is equivalent to `REST_URL/set/foo/$VALUE/EX/100`.

#### POST Command in Body

Alternatively, you can send the whole command in the request body as a single
JSON array. Array's first element must be the command name and command
parameters should be appended next to each other in the same order as Redis
protocol.

```shell
curl -X POST -d '[COMMAND, ARG1, ARG2,.., ARGN]' REST_URL
```

For example, Redis command `SET foo bar EX 100` can be sent inside the request
body as:

```shell
curl -X POST -d '["SET", "foo", "bar", "EX", 100]' https://us1-merry-cat-32748.upstash.io \
 -H "Authorization: Bearer 2553feg6a2d9842h2a0gcdb5f8efe9934"
```

## HTTP Codes

* `200 OK`: When request is accepted and successfully executed.

* `400 Bad Request`: When there's a syntax error, an invalid/unsupported command
  is sent or command execution fails.

* `401 Unauthorized`: When authentication fails; auth token is missing or
  invalid.

* `405 Method Not Allowed`: When an unsupported HTTP method is used. Only
  `HEAD`, `GET`, `POST` and `PUT` methods are allowed.

## Response

REST API returns a JSON response by default. When command execution is successful, response
JSON will have a single `result` field and its value will contain the Redis
response. It can be either;

* a `null` value

```json
{ "result": null }
```

* an integer

```json
{ "result": 137 }
```

* a string

```json
{ "result": "value" }
```

* an array value:

```json
{ "result": ["value1", null, "value2"] }
```

If command is rejected or fails, response JSON will have a single `error` field
with a string value explaining the failure:

```json
{"error":"WRONGPASS invalid password"}

{"error":"ERR wrong number of arguments for 'get' command"}
```

### Base64 Encoded Responses

If the response contains an invalid utf-8 character, it will be replaced with
a � (Replacement character U+FFFD). This can happen when you are using binary
operations like `BITOP NOT` etc.

If you prefer the raw response in base64 format, you can achieve this by setting
the `Upstash-Encoding` header to `base64`. In this case, all strings in the response
will be base64 encoded, except for the "OK" response.

```shell
curl https://us1-merry-cat-32748.upstash.io/SET/foo/bar \
 -H "Authorization: Bearer 2553feg6a2d9842h2a0gcdb5f8efe9934" \
 -H "Upstash-Encoding: base64"

# {"result":"OK"}

curl https://us1-merry-cat-32748.upstash.io/GET/foo \
 -H "Authorization: Bearer 2553feg6a2d9842h2a0gcdb5f8efe9934" \
 -H "Upstash-Encoding: base64"

# {"result":"YmFy"}
```

### RESP2 Format Responses

REST API returns a JSON response by default and the response content type is set to `application/json`.

If you prefer the binary response in RESP2 format, you can achieve this by setting
the `Upstash-Response-Format` header to `resp2`. In this case, the response content type
is set to `application/octet-stream` and the raw response is returned as binary similar to a TCP-based Redis client.

The default value for this option is `json`.
Any format other than `json` and `resp2` is not allowed and will result in a HTTP 400 Bad Request.

This option is not applicable to `/multi-exec` transactions endpoint, as it only returns response in JSON format.
Additionally, setting the `Upstash-Encoding` header to `base64` is not permitted when the `Upstash-Response-Format` is set to `resp2`
and will result in a HTTP 400 Bad Request.

```shell
curl https://us1-merry-cat-32748.upstash.io/SET/foo/bar \
 -H "Authorization: Bearer 2553feg6a2d9842h2a0gcdb5f8efe9934" \
 -H "Upstash-Reponse-Format: resp2"

# +OK\r\n

curl https://us1-merry-cat-32748.upstash.io/GET/foo \
 -H "Authorization: Bearer 2553feg6a2d9842h2a0gcdb5f8efe9934" \
 -H "Upstash-Reponse-Format: resp2"

# $3\r\nbar\r\n
```

## Pipelining

Upstash REST API provides support for command pipelining, allowing you to send
multiple commands as a batch instead of sending them individually and waiting
for responses. With the pipeline API, you can include several commands in a
single HTTP request, and the response will be a JSON array. Each item in the
response array corresponds to the result of a command in the same order as they
were included in the pipeline.

API endpoint for command pipelining is `/pipeline`. Pipelined commands should be
send as a two dimensional JSON array in the request body, each row containing
name of the command and its arguments.

**Request syntax**:

```shell
curl -X POST https://us1-merry-cat-32748.upstash.io/pipeline \
 -H "Authorization: Bearer $TOKEN" \
 -d '
    [
      ["CMD_A", "arg0", "arg1", ..., "argN"],
      ["CMD_B", "arg0", "arg1", ..., "argM"],
      ...
    ]
    '
```

**Response syntax**:

```json
[{"result":"RESPONSE_A"},{"result":"RESPONSE_B"},{"error":"ERR ..."}, ...]
```

<Note>
  Execution of the pipeline is _not atomic_. Even though each command in the
  pipeline will be executed in order, commands sent by other clients can
  interleave with the pipeline. Use [transactions](#transactions) API instead if
  you need atomicity.
</Note>

For example you can write the `curl` command below to send following Redis
commands using pipeline:

```redis
SET key1 valuex
SETEX key2 13 valuez
INCR key1
ZADD myset 11 item1 22 item2
```

```shell
curl -X POST https://us1-merry-cat-32748.upstash.io/pipeline \
 -H "Authorization: Bearer 2553feg6a2d9842h2a0gcdb5f8efe9934" \
 -d '
    [
      ["SET", "key1", "valuex"],
      ["SETEX", "key2", 13, "valuez"],
      ["INCR", "key1"],
      ["ZADD", "myset", 11, "item1", 22, "item2"]
    ]
    '
```

And pipeline response will be:

```json
[
  { "result": "OK" },
  { "result": "OK" },
  { "error": "ERR value is not an int or out of range" },
  { "result": 2 }
]
```

You can use pipelining when;

* You need more throughput, since pipelining saves from multiple round-trip
  times. (_But beware that latency of each command in the pipeline will be equal
  to the total latency of the whole pipeline._)
* Your commands are independent of each other, response of a former command is
  not needed to submit a subsequent command.

## Transactions

Upstash REST API supports transactions to execute multiple commands atomically.
With transactions API, several commands are sent using a single HTTP request,
and a single JSON array response is returned. Each item in the response array
corresponds to the command in the same order within the transaction.

API endpoint for transaction is `/multi-exec`. Transaction commands should be
send as a two dimensional JSON array in the request body, each row containing
name of the command and its arguments.

**Request syntax**:

```shell
curl -X POST https://us1-merry-cat-32748.upstash.io/multi-exec \
 -H "Authorization: Bearer $TOKEN" \
 -d '
    [
      ["CMD_A", "arg0", "arg1", ..., "argN"],
      ["CMD_B", "arg0", "arg1", ..., "argM"],
      ...
    ]
    '
```

**Response syntax**:

In case when transaction is successful, multiple responses corresponding to each
command is returned in json as follows:

```json
[{"result":"RESPONSE_A"},{"result":"RESPONSE_B"},{"error":"ERR ..."}, ...]
```

If transaction is discarded as a whole, a single error is returned in json as
follows:

```json
{ "error": "ERR ..." }
```

A transaction might be discarded in following cases:

* There is a syntax error on the transaction request.
* At least one of the commands is unsupported.
* At least one of the commands exceeds the
  [max request size](../troubleshooting/max_request_size_exceeded).
* At least one of the commands exceeds the
  [daily request limit](../troubleshooting/max_daily_request_limit).

Note that a command may still fail even if it is a supported and valid command.
In that case, all commands will be executed. Upstash Redis will not stop the
processing of commands. This is to provide same semantics with Redis when there
are
[errors inside a transaction](https://redis.io/docs/manual/transactions/#errors-inside-a-transaction).

**Example**:

You can write the `curl` command below to send following Redis commands using
REST transaction API:

```
MULTI
SET key1 valuex
SETEX key2 13 valuez
INCR key1
ZADD myset 11 item1 22 item2
EXEC
```

```shell
curl -X POST https://us1-merry-cat-32748.upstash.io/multi-exec \
 -H "Authorization: Bearer 2553feg6a2d9842h2a0gcdb5f8efe9934" \
 -d '
    [
      ["SET", "key1", "valuex"],
      ["SETEX", "key2", 13, "valuez"],
      ["INCR", "key1"],
      ["ZADD", "myset", 11, "item1", 22, "item2"]
    ]
    '
```

And transaction response will be:

```json
[
  { "result": "OK" },
  { "result": "OK" },
  { "error": "ERR value is not an int or out of range" },
  { "result": 2 }
]
```

## Monitor Command

Upstash REST API provides Redis [`MONITOR`](https://redis.io/docs/latest/commands/monitor/) command using
[Server Send Events](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events) mechanism. API endpoint is `/monitor`.

```shell
curl -X POST https://us1-merry-cat-32748.upstash.io/monitor \
  -H "Authorization: Bearer 2553feg6a2d9842h2a0gcdb5f8efe9934" \
  -H "Accept:text/event-stream"
```

This request will listen for Redis monitor events and incoming data will be received as:

```
data: "OK"
data: 1721284005.242090 [0 0.0.0.0:0] "GET" "k"
data: 1721284008.663811 [0 0.0.0.0:0] "SET" "k" "v"
data: 1721284025.561585 [0 0.0.0.0:0] "DBSIZE"
data: 1721284030.601034 [0 0.0.0.0:0] "KEYS" "*"
```

## Subscribe & Publish Commands

Simiar to `MONITOR` command, Upstash REST API provides Redis [`SUBSCRIBE`](https://redis.io/docs/latest/commands/subscribe/) and
[`PUBLISH`](https://redis.io/docs/latest/commands/publish/) commands. The `SUBSCRIBE` endpoint works using
[Server Send Events](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events) mechanism.
API endpoints are `/subscribe` and `/publish`

Following request will subscribe to a channel named `chat`:

```shell
curl -X POST https://us1-merry-cat-32748.upstash.io/subscribe/chat \
  -H "Authorization: Bearer 2553feg6a2d9842h2a0gcdb5f8efe9934" \
  -H "Accept:text/event-stream"
```

Following request will publish to a channel named `chat`:

```shell
curl -X POST https://us1-merry-cat-32748.upstash.io/publish/chat/hello \
  -H "Authorization: Bearer 2553feg6a2d9842h2a0gcdb5f8efe9934"
```

The subscriber will receive incoming messages as:

```
data: subscribe,chat,1
data: message,chat,hello
data: message,chat,how are you today?
```

## Security and Authentication

You need to add a header to your API requests as `Authorization: Bearer $TOKEN`
or set the token as a url parameter `_token=$TOKEN`.

```shell
curl -X POST https://us1-merry-cat-32748.upstash.io/info \
  -H "Authorization: Bearer 2553feg6a2d9842h2a0gcdb5f8efe9934"
```

```shell
curl -X POST https://us1-merry-cat-32748.upstash.io/info?_token=2553feg6a2d9842h2a0gcdb5f8efe9934
```

Upstash by default provides two separate access tokens per database: "Standard"
and "Read Only".

* **Standard** token has full privilege over the database, can execute any
  command.

* **Read Only** token permits access to the read commands only. Some powerful
  read commands (e.g. SCAN, KEYS) are also restricted with read only token. It
  makes sense to use _Read Only_ token when you access Upstash Redis from web
  and mobile clients where the token is exposed to public.

You can get/copy the tokens by clicking copy button next to
`UPSTASH_REDIS_REST_TOKEN` in REST API section of the console. For the _Read
Only_ token, just enable the "Read-Only Token" switch.

<img />

<Warning>
  Do not expose your _Standard_ token publicly. _Standard_ token has full
  privilege over the database. You can expose the _Read Only_ token as it has
  access to read commands only. You can revoke both _Standard_ and _Read Only_
  tokens by resetting password of your database.
</Warning>

### REST Token for ACL Users

In addition to the tokens provided by default, you can create REST tokens for
the users created via [`ACL SETUSER`](https://redis.io/commands/acl-setuser/)
command. Upstash provides a custom `ACL` subcommand to generate REST tokens:
`ACL RESTTOKEN`. It expects two arguments; username and user's password. And
returns the REST token for the user as a string response.

```
ACL RESTTOKEN <username> <password>
    Generate a REST token for the specified username & password.
    Token will have the same permissions with the user.
```

You can execute `ACL RESTTOKEN` command via `redis-cli`:

```shell
redis-cli> ACL RESTTOKEN default 35fedg8xyu907d84af29222ert
"AYNgAS2553feg6a2d9842h2a0gcdb5f8efe9934DQ="
```

Or via CLI on the Upstash console:

<img />

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.

## Cost and Pricing

Upstash pricing is based on per command/request. So the same pricing listed in
our [pricing](https://upstash.com/pricing/redis) applies to your REST calls too.

## Metrics and Monitoring

In the current version, we do not expose any metrics specific to API calls in
the console. But the metrics of the database backing the API should give a good
summary about the performance of your APIs.

## REST - Redis API Compatibility

| Feature                                                       | REST Support? |                               Notes                               |
| ------------------------------------------------------------- | :-----------: | :---------------------------------------------------------------: |
| [String](https://redis.io/commands/?group=string)             |      ✅       |                                                                   |
| [Bitmap](https://redis.io/commands/?group=bitmap)             |      ✅       |                                                                   |
| [Hash](https://redis.io/commands/?group=hash)                 |      ✅       |                                                                   |
| [List](https://redis.io/commands/?group=list)                 |      ✅       | Blocking commands (BLPOP - BRPOP - BRPOPLPUSH) are not supported. |
| [Set](https://redis.io/commands/?group=set)                   |      ✅       |                                                                   |
| [SortedSet](https://redis.io/commands/?group=sorted_set)      |      ✅       |    Blocking commands (BZPOPMAX - BZPOPMIN) are not supported.     |
| [Geo](https://redis.io/commands/?group=geo)                   |      ✅       |                                                                   |
| [HyperLogLog](https://redis.io/commands/?group=hyperloglog)   |      ✅       |                                                                   |
| [Transactions](https://redis.io/commands/?group=transactions) |      ✅       |             WATCH/UNWATCH/DISCARD are not supported               |
| [Generic](https://redis.io/commands/?group=generic)           |      ✅       |                                                                   |
| [Server](https://redis.io/commands/?group=server)             |      ✅       |                                                                   |
| [Scripting](https://redis.io/commands/?group=scripting)       |      ✅       |                                                                   |
| [Pub/Sub](https://redis.io/commands/?group=pubsub)            |      ✅       |                                                                   |
| [Connection](https://redis.io/commands/?group=connection)     |      ⚠️       |                 Only PING and ECHO are supported.                 |
| [JSON](https://redis.io/commands/?group=json)                 |      ✅       |                                                                   |
| [Streams](https://redis.io/commands/?group=stream)            |      ✅       |    Supported, except blocking versions of XREAD and XREADGROUP.   |
| [Cluster](https://redis.io/commands#cluster)                  |      ❌       |                                                                   |

# Security
Source: https://upstash.com/docs/redis/features/security

Upstash has a set of features to help you secure your data. We will list them
and at the end of the section we will list the best practices to improve
security of database.

## TLS

TLS is always enabled on Upstash Redis databases. The data transfer between the client and database is
encrypted.

## Redis ACL

With Redis ACL, you can improve security by restricting a user's access to
commands and keys, so that untrusted clients have no access and trusted clients
have just the minimum required access level to the database. Moreover it
improves operational safety, so that clients or users accessing Redis are not
allowed to damage the data or the configuration due to errors or mistakes. Check
[Redis ACL documentation](https://redis.io/docs/latest/operate/oss_and_stack/management/security/acl/). If you
are using the REST API, you can still benefit from ACLs as explained
[here](/docs/redis/features/restapi#rest-token-for-acl-users)

ACL is available on all paid databases.

## Database Credentials

When you create a database, a secure password is generated. Upstash keeps the
password encrypted. Use environment variables or your provider's secret
management system (e.g. AWS Secrets Manager, Vercel Secrets) to keep them. Do
not use them hardcoded in your code. If your password is leaked, reset the
password using Upstash console.

## Encryption at Rest

Encryption at Rest encrypts the block storage where your data is persisted and
stored. It is available with [Prod Pack](/docs/redis/overall/enterprise#prod-pack-features) add-on.

## Application Level Encryption

Client side encryption can be used to encrypt data through application
lifecycle. Client-side encryption is used to help protect data in use. This
comes with some limitations. Operations that must operate on the data, such as
increments, comparisons, and searches will not function properly. You can write
client-side encryption logic directly in your own application or use functions
built into clients such as the Java Lettuce cipher codec. We have plans to
support encryption in our SDKs.

## IP Allowlisting

We can restrict the access to your database to a set of IP addresses which will
have access to your database. This is quite a strong way to secure your
database, but it has some limitations. For example you can not know the IP
addresses in serverless platforms such AWS Lambda and Vercel functions.

## VPC Peering

VPC Peering enables you to connect to Upstash from your own VPC using private
IP. Database will not be accessible from the public network. Database and your
application can run in the same subnet which also minimizes data transfer costs.
VPC Peering is only available for Pro databases.

## Private Link

AWS Private link provides private connectivity between Upstash Database and your
Redis client inside AWS infrastructure. Private link is only available for
Pro databases.

# Compliance
Source: https://upstash.com/docs/redis/help/compliance

## Upstash Legal & Security Documents

* [Upstash Terms of Service](https://upstash.com/static/trust/terms.pdf)
* [Upstash Privacy Policy](https://upstash.com/static/trust/privacy.pdf)
* [Upstash Data Processing Agreement](https://upstash.com/static/trust/dpa.pdf)
* [Upstash Technical and Organizational Security Measures](https://upstash.com/static/trust/security-measures.pdf)
* [Upstash Subcontractors](https://upstash.com/static/trust/subprocessors.pdf)

## Is Upstash SOC2 Compliant?

As of July 2023, Upstash Redis is SOC2 compliant. Check our [trust page](https://trust.upstash.com/) for details.

## Is Upstash ISO-27001 Compliant?

We are in process of getting this certification. Contact us
([support@upstash.com](mailto:support@upstash.com)) to learn about the expected
date.

## Is Upstash GDPR Compliant?

Yes. For more information, see our
[Privacy Policy](https://upstash.com/static/trust/privacy.pdf). We acquire DPAs
from each [subcontractor](https://upstash.com/static/trust/subprocessors.pdf)
that we work with.

## Is Upstash HIPAA Compliant?

Upstash is currently not HIPAA compliant. Contact us
([support@upstash.com](mailto:support@upstash.com)) if HIPAA is important for
you and we can share more details.

## Is Upstash PCI Compliant?

Upstash does not store personal credit card information. We use Stripe for
payment processing. Stripe is a certified PCI Service Provider Level 1, which is
the highest level of certification in the payments industry.

## Does Upstash conduct vulnerability scanning and penetration tests?

Yes, we use third party tools and work with pen testers. We share the results
with Enterprise customers. Contact us
([support@upstash.com](mailto:support@upstash.com)) for more information.

## Does Upstash take backups?

Yes, we take regular snapshots of the data cluster to the AWS S3 platform.

## Does Upstash encrypt data?

Customers can enable TLS while creating database/cluster, and we recommend it
for production databases/clusters. Also we encrypt data at rest at request of
customers.

# Frequently Asked Questions
Source: https://upstash.com/docs/redis/help/faq

## What is Upstash Redis?

Upstash is a serverless database service compatible with Redis® API.

## What is a Serverless Database?

* You do not have to manage and provision servers.
* You do not deal with configuring or maintaining any server.
* You just use the service and pay what you use. If you are not using it, you should not be paying.

## What are the use cases?

Upstash works for all the common usecases for Redis®. You can use Upstash in your serverless stack. In addition, you can use Upstash as storage (or caching) for your serverless functions. See [Use Cases](/docs/redis/overall/usecases) for more.

## Do you support all Redis® API?

Most of them. See [Redis® API Compatibility](/docs/redis/overall/compatibility) for the list of supported commands.

## Can I use any Redis client?

Yes, Upstash is compatible Redis client protocol.

## Which cloud providers do you support?

Upstash Redis is available on AWS, GCP and Fly.io.

## Which regions do you support in AWS?

We start with AWS-US-EAST-1 (Virginia), GCP-US-CENTRAL-1 (IOWA), AWS-US-WEST-1 (N. California), AWS-EU-WEST-1 (Ireland), AWS-APN-NE-1 (Japan). We will add new regions soon. You can expedite this by telling us your use case and the region you need by emailing to [support@upstash.com](mailto:support@upstash.com)

## Should my client be hosted in the AWS to use Upstash?

No. Your client can be anywhere but the clients in AWS regions will give you better performance.

## How do you compare Upstash with ElastiCache?

Upstash is serverless. With ElastiCache, you pay even you do not use the database. See [Compare](/docs/redis/overall/compare) for more info.

## How do you compare Upstash with Redis Labs or Compose.io?

Upstash is serverless. With Redis Labs or Compose.io, you always pay a lot when your data size is big but your traffic is low. In Upstash, the pricing is based on per request. See [Compare](/docs/redis/overall/compare) for more info.

## Do you persist data?

Yes, by default we write data to the disk. So in case of a failure you should not lose any data.

## Do you support Redis Cluster?

We support replication in Premium type database. We do not support sharding yet.

## I have database with 10GB data, I pay nothing if I do not use it. Is that correct?

You only pay for the disk storage cost that is \$0.25 per GB. For your case, you will pay \$2.5 monthly.

## What happens when I exceed the request limit on Free Database (10.000 requests per day)?

The exceeding commands return exception.

## What happens if my database exceeds the max commands-per-second limit?

When your database reaches its commands-per-second limit, requests are temporarily throttled.
In most cases, commands wait until capacity becomes available again, which may increase latency for a short time. Once traffic drops below the limit (or the plan is upgraded), normal request flow resumes.

## When I upgrade my free database, do I lose data?

You do not lose data but clients may disconnect and reconnect.

## Upstash is much cheaper than Elasticache and Redis Labs for big data sizes (> 10GB). How is that possible?

Upstash storage layer is multi tiered. We keep your data in both memory and block storage (disk). The entries that are not accessed frequently are removed from the memory but stored in disk. Latency overhead of idle entries is limited thanks to the SSD based storage. Multi tiered storage allows us to provide more flexible pricing.

## Will my data be safe?

Upstash is a GDPR compliant company. We do not share any user data with third parties. See our [Legal Documents](/docs/common/help/legal) for more information.

## What happens if my database is not used?

Free tier databases are archived after a minimum of 14 days of inactivity. Users get several warning emails prior to this operation. Archival means backing up user data and removing the database instance.

If you wish to keep your database endpoint active for a longer period of inactivity, consider switching to a paid plan.

<Note>
  No data is lost due to archival. When a free tier database is archived due to inactivity, we take a backup of the data so users can create a new database and restore their data from the Upstash Console.
</Note>

## How do you handle the noisy neighbour problem? Do other tenants affect my database?

Databases are isolated on some aspects but still share some hardware resources such as CPU or network. To avoid noisy neighbor influence on these resources, there are specific quotas for each database. When they reach any of these quotas they are throttled using a backoff strategy. When multiple databases sharing the same hardware are close to the limits, our system can add new resources to the pool and/or migrate some of the databases to distribute the load.

Also if a database exceeds its quotas very frequently, we notify users whether they want to upgrade to an upper plan. Databases in enterprise plans are placed either on dedicated or more isolated hardware due to higher resource needs.

# Integration with Third Parties & Partnerships
Source: https://upstash.com/docs/redis/help/integration

## 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

<Info>
  Before starting development to integrate Upstash into your product, please
  send an email to partnerships@upstash.com for further assistance and guidance.
</Info>

**General Flow (High level user flow)**

1. User clicks **`Connect Upstash`** button on your platform’s surface (GUI, Web App)
2. This initiates the OAuth 2.0 flow, which opens a new browser page displaying the **`Upstash Login Page`**.
3. If this is an existing user, user logins with their Upstash credentials otherwise they can directly sign up for a new Upstash account.
4. Browser window redirects to **`Your account has been connected`** page and authentication window automatically closes.
5. After the user returns to your interface, they see their Upstash Account is now connected.

## Technical Design (SPA - Regular Web Application)

1. Users click `Connect Upstash` button from Web App.
2. Web App initiate Upstash OAuth 2.0 flow. Web App can use
   [Auth0 native libraries](https://auth0.com/docs/libraries).

<Note>
  Please reach partnerships@upstash.com to receive client id and callback url.
</Note>

3. After user returns from OAuth 2.0 flow then web app will have JWT token. Web
   App can generate Developer Api key:

```bash
curl -XPOST https://api.upstash.com/apikey \
    -H "Authorization: Bearer JWT_KEY" \
    -H "Content-Type: application/json" \
    -d '{ "name": "APPNAME_API_KEY_TIMESTAMP" }'
```

4. Web App need to save Developer Api Key to the backend.

## Technical Design ( GUI Apps )

<img />

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
```

<Note>Please reach partnerships@upstash.com to receive client id.</Note>

4. After user authenticated Auth0 will redirect user to
   `localhost:3000/?code=XXXXXX`
5. APP can return some nice html response when Auth0 returns to `localhost:3000`

6. After getting `code` parameter from the URL query, GUI App will make http
   call to the Auth0 code exchange api. Example CURL request

```bash
curl -XPOST 'https://auth.upstash.com/oauth/token' \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data 'grant_type=authorization_code --data audience=upstash-api' \
  --data 'client_id=XXXXXXXXXXX' \
  --data 'code=XXXXXXXXXXXX' \
  --data 'redirect_uri=localhost:3000'
```

Response:

```json
{
  "access_token": "XXXXXXXXXX",
  "refresh_token": "XXXXXXXXXXX",
  "scope": "offline_access",
  "expires_in": 172800,
  "token_type": "Bearer"
}
```

7. After 6th Step the response will include `access_token`, it has 3 days TTL.
   GUI App will call Upstash API to get a developer api key:

```bash
curl https://api.upstash.com/apikey -H "Authorization: Bearer JWT_KEY" -d '{ "name" : "APPNAME_API_KEY_TIMESTAMP" }'
```

8. GUI App will save Developer Api key locally. Then GUI App can call any
   Upstash Developer API [developer.upstash.com/](https://developer.upstash.com/)

## Managing Resources

After obtaining Upstash Developer Api key, your platform surface (web or GUI) can call Upstash API. For example **[Create Database](https://developer.upstash.com/#create-database-global)**, **[List Database](https://developer.upstash.com/#list-databases)**

In this flow, you can ask users for region information and name of the database then can call Create Database API to complete the task

Example CURL request:

```bash
curl -X POST \
  https://api.upstash.com/v2/redis/database \
  -u 'EMAIL:API_KEY' \
  -d '{"name":"myredis", "region":"global", "primary_region":"us-east-1", "read_regions":["us-west-1","us-west-2"], "tls": true}'
```

# Legal
Source: https://upstash.com/docs/redis/help/legal

## Upstash Legal Documents

* [Upstash Terms of Service](https://upstash.com/trust/terms.pdf)
* [Upstash Privacy Policy](https://upstash.com/trust/privacy.pdf)
* [Upstash Subcontractors](https://upstash.com/trust/subprocessors.pdf)

# Managing Healthcare Data
Source: https://upstash.com/docs/redis/help/managing-healthcare-data

You can use Upstash Redis to store and process Protected Health Information (PHI). You are responsible for the following:

* **Signing a Business Associate Agreement (BAA)** with Upstash. This is provided as part of our Enterprise offering. Email [support@upstash.com](mailto:support@upstash.com) to get started.
* **Marking specific databases as HIPAA databases** and addressing security issues raised by the Upstash team.
* **Ensuring MFA is enabled** on all Upstash Console accounts.
  * Enforce MFA as a requirement to access the organization
* **Enabling Prod Pack** which provides encryption at rest and advanced security features (already included in the Enterprise plan).
* **Enabling Credential Protection** to prevent storing credentials in Upstash infrastructure and limit console access requiring database credentials.
* **Configuring IP allowlist** to restrict database access to authorized networks.
* **Enabling daily backups** to validate recoverability and meet retention requirements.
* **Complying with encryption requirements** in the HIPAA Security Rule. Data is encrypted at rest and in transit by Upstash. You can consider encrypting the data at your application layer.
* **Ensuring that PHI is stored only within your database**. Storing PHI in resource names or other locations is strictly prohibited.
* **Ensuring that PHI is stored only in values of data structures, not in identifiers or keys**. Avoid logging keys anywhere.
* **Not using public endpoints** to process PHI.
* **Not transferring databases** to a non-HIPAA organization.

<Note>
  For a comprehensive guide on implementing these responsibilities in production, see our [Production Checklist](/docs/redis/help/production-checklist). For questions about managing healthcare data, contact our support team at [support@upstash.com](mailto:support@upstash.com).
</Note>

# Production Checklist
Source: https://upstash.com/docs/redis/help/production-checklist

This checklist provides essential recommendations for securing and optimizing your Upstash databases for production workloads.

## Security Features

### Enable Prod Pack
Prod Pack provides enterprise-grade security and monitoring features:

* 99.99% uptime SLA
* SOC-2 Type 2 report available
* Encryption at Rest
* Advanced monitoring (Prometheus, Datadog)
* Multi-Zone High Availability
* High availability for read regions

<Note>
  Prod Pack is available as a $200/month add-on per database for all paid plans except Free tier. It is already included within Enterprise Plan.
</Note>

### Enable Credential Protection
Protect your database credentials (Prod Pack feature):

* Credentials are never stored in Upstash infrastructure
* Credentials are displayed only once during enablement
* Console features requiring database access are disabled

<Warning>
  Disabling this feature will permanently revoke current credentials and generate new ones.
</Warning>

### Configure IP Allowlist
Restrict database access to specific IP addresses:

* Available on all plans except Free tier
* Supports IPv4 addresses and CIDR blocks
* Multiple IP ranges can be configured

### Implement Redis ACL
Use Redis Access Control Lists to restrict user access:

* Available on all paid plans
* Create users with minimal required permissions
* Available for both TCP connections and REST API
* Use `ACL RESTTOKEN` command to generate REST tokens

### Enable Multi-Factor Authentication
Enable MFA on your Upstash account for enhanced security:

* Use your existing authentication provider (Google, GitHub, Amazon)
* Consider using a dedicated email/password account for production
* Force MFA for all team members to ensure consistent security
* Regularly review account access and team member permissions

### Secure Credential Management
Follow these best practices:

* Never hardcode credentials in your application code
* Use environment variables or secret management systems
* Reset passwords immediately if credentials are compromised
* Use Read-Only tokens for public-facing applications

## Network Security

### TLS Encryption
TLS is always enabled on Upstash Redis databases.

### VPC Peering (Enterprise)
Connect databases to your VPCs using private IP:

* Database becomes inaccessible from public networks
* Minimizes data transfer costs
* Available for Enterprise customers

## Monitoring & Observability

### Enable Advanced Monitoring
Prod Pack includes comprehensive monitoring:

* Prometheus integration
* Datadog integration
* Extended console metrics (up to one month)

## High Availability & Backup

### Enable Daily Backups
Configure automated daily backups for data protection:

* Available on all paid plans
* Backup retention up to 3 days with Prod Pack
* Hourly backups with customizable retention (Enterprise)

### Global Replication
For global applications, consider using Global Database:

* Distribute data across multiple regions
* Minimize latency for users worldwide
* Enhanced disaster recovery capabilities

## Compliance & Governance

### SOC-2 Compliance
Prod Pack and Enterprise plans include SOC-2 Type 2 compliance:

* Request SOC-2 report from [trust.upstash.com](https://trust.upstash.com/)
* Available for production workloads

### Enterprise Features
For enterprise customers:

* HIPAA compliance available
* SAML SSO integration
* Access logs available
* Custom resource allocation

## Pre-Production Checklist

Before going live, ensure you have:

* [ ] Prod Pack enabled (strongly recommended)
* [ ] Credential Protection enabled
* [ ] IP Allowlist configured
* [ ] MFA enabled on your account
* [ ] Daily backups enabled
* [ ] Monitoring and alerts configured
* [ ] Environment variables secured
* [ ] Error handling tested

## Additional Resources

* [Security Features](/docs/redis/features/security)
* [Prod Pack & Enterprise](/docs/redis/overall/enterprise)
* [Backup & Restore](/docs/redis/features/backup)
* [Global Database](/docs/redis/features/globaldatabase)
* [Monitoring & Metrics](/docs/redis/howto/metrics-and-charts)
* [Compliance Information](/docs/common/help/compliance)
* [Professional Support](/docs/common/help/prosupport)

For additional assistance with production deployment, contact our support team at [support@upstash.com](mailto:support@upstash.com).

# Shared Responsibility Model
Source: https://upstash.com/docs/redis/help/shared-responsibility-model

The Shared Responsibility Model defines the security and operational responsibilities between Upstash and our customers when using Upstash Redis. This model ensures clarity in who is responsible for what aspects of security, compliance, and operations.

## Overview

Upstash Redis is a serverless database service that provides Redis® API compatibility with automatic scaling, high availability, and enterprise-grade security features. The shared responsibility model divides responsibilities into three main categories:

* **Upstash Responsibilities**: Infrastructure, platform, and service-level security
* **Customer Responsibilities**: Data, application, and access management
* **Shared Responsibilities**: Configuration, monitoring, and incident response

## Responsibility Matrix

| Category | Upstash | Customer | Shared |
|----------|---------|----------|--------|
| **Infrastructure Security** | ✅ Physical security, network infrastructure, DDoS protection, hardware maintenance | ❌ | ❌ |
| **Platform Security** | ✅ OS security, Redis updates, container security, infrastructure monitoring | ❌ | ❌ |
| **Service Availability** | ✅ 99.99% SLA (Prod Pack), multi-zone high availability (Prod Pack), multi-region replication, auto-scaling, disaster recovery | ❌ | ❌ |
| **Data Encryption** | ✅ TLS in transit, encryption at rest (Prod Pack), key management | ❌ | ❌ |
| **Compliance** | ✅ SOC 2 (Prod Pack), GDPR, HIPAA (Enterprise) | ❌ | ❌ |
| **Data Management** | ❌ | ✅ Data classification, retention policies, quality controls | ❌ |
| **Application Security** | ❌ | ✅ Secure development, input validation, authentication, client-side encryption | ❌ |
| **Access Control** | ❌ | ✅ Redis ACL, user permissions, credential management, MFA | ❌ |
| **Network Security** | ❌ | ✅ IP allowlist, network segmentation, client security | ❌ |
| **Security Configuration** | ❌ | ❌ | ✅ ACL setup, security policies |
| **Monitoring** | ✅ Infrastructure monitoring, incident response | ✅ Application monitoring, custom metrics | ✅ Performance monitoring, security monitoring |
| **Incident Response** | ✅ Infrastructure incidents, service restoration | ✅ Application incidents, data incidents | ✅ Incident coordination, root cause analysis |

## Key Responsibilities

<AccordionGroup>
  <Accordion title="Upstash Responsibilities">
    **Infrastructure & Platform:**
    * Physical security, network infrastructure, DDoS protection
    * OS security, Redis updates, container security
    * 99.99% uptime SLA (Prod Pack), multi-zone high availability for read regions (Prod Pack), multi-region replication, auto-scaling
    * TLS encryption, encryption at rest (Prod Pack), key management
    * SOC 2 (Prod Pack), GDPR, HIPAA (Enterprise)
    * 24/7 infrastructure monitoring and incident response
  </Accordion>

<Accordion title="Customer Responsibilities">
    **Data & Application Security:**
    * Architecture: retries/backoff, idempotency, timeouts; region/topology choices
    * Data governance: classification, retention, integrity
    * App security: secure coding, input validation, authN/authZ
    * Access: Redis ACL (least privilege), credential hygiene and rotation
    * Network: IP allowlist and client hardening
    * Ops: monitoring/alerts, error handling, budgets/limits
  </Accordion>

<Accordion title="Shared Responsibilities">
    **Configuration & Operations:**
    * ACL, IP allowlist, and Prod Pack configuration
    * Compliance requirements understanding and implementation
    * Performance monitoring setup and alerting
    * Incident coordination and root cause analysis
  </Accordion>
</AccordionGroup>

# Support & Contact Us
Source: https://upstash.com/docs/redis/help/support

## Community

[Upstash Discord Channel](https://upstash.com/discord) is the best way to
interact with the community.

## Team

You can contact the team
via [support@upstash.com](mailto:support@upstash.com) for technical support as
well as questions and feedback.

## Follow Us

## Professional Support

Get [Professional Support](/docs/common/help/prosupport) from the Upstash team.

# Uptime Monitor
Source: https://upstash.com/docs/redis/help/uptime

## Status Page

You can track the uptime status of Upstash databases in
[Upstash Status Page](https://status.upstash.com)

## Latency Monitor

You can see the average latencies for different regions in
[Upstash Latency Monitoring](https://latency.upstash.com) page

# Connect Your Client
Source: https://upstash.com/docs/redis/howto/connect-client

Upstash works with Redis® API, that means you can use any Redis client with
Upstash. At the [Redis Clients](https://redis.io/clients) page you can find the
list of Redis clients in different languages.

Simplest way to connect to your database is to use `redis-cli`.
Because it is already covered in [Getting Started](../overall/getstarted), we
will skip it here.

## Database

After completing the [getting started](../overall/getstarted) guide, you will
see the database page as below:

<img />

The connection details required for Redis clients are displayed here: **Endpoint**,
**Port**, and **Token** (which is also the password of the database). You can also
find the environment variables `UPSTASH_REDIS_REST_URL` and`UPSTASH_REDIS_REST_TOKEN`
on this page.

Below, we will provide examples from popular Redis clients, but the information above should help you configure all Redis clients similarly.

<Note>
  TLS is enabled by default for all Upstash Redis databases. It's not possible
  to disable it.
</Note>

## @upstash/redis

[@upstash/redis](https://github.com/upstash/redis-js) is the official SDK developed
and maintained by Upstash. It is HTTP-based, which makes it ideal for serverless
environments like Vercel and Cloudflare Workers. In highly concurrent serverless
workloads, TCP-based clients can run into connection issues.

```typescript
import { Redis } from "@upstash/redis";

const redis = new Redis({
  url: "UPSTASH_REDIS_REST_URL",
  token: "UPSTASH_REDIS_REST_TOKEN",
});

(async () => {
  try {
    const data = await redis.get("key");
    console.log(data);
  } catch (error) {
    console.error(error);
  }
})();
```

See the [Connect with @upstash/redis page](/docs/redis/howto/connect-with-upstash-redis) for more information.

## Node.js

**Library**: [ioredis](https://github.com/luin/ioredis)

```javascript
const Redis = require("ioredis");

let client = new Redis("rediss://:YOUR_PASSWORD@YOUR_ENDPOINT:YOUR_PORT");
await client.set("foo", "bar");
let x = await client.get("foo");
console.log(x);
```

## Python

**Library**: [redis-py](https://github.com/andymccurdy/redis-py)

```python
import redis
r = redis.Redis(
host= 'YOUR_ENDPOINT',
port= 'YOUR_PORT',
password= 'YOUR_PASSWORD',
ssl=True)
r.set('foo','bar')
print(r.get('foo'))
```

## Java

**Library**: [jedis](https://github.com/xetorthio/jedis)

```java
Jedis jedis = new Jedis("YOUR_ENDPOINT", "YOUR_PORT", true);
jedis.auth("YOUR_PASSWORD");
jedis.set("foo", "bar");
String value = jedis.get("foo");
System.out.println(value);
```

<Info>
  Jedis does not offer command level retry config by default, but you can handle
  retries using connection pool. Check [Retrying a command after a connection
  failure](https://redis.io/docs/latest/develop/clients/jedis/connect/#retrying-a-command-after-a-connection-failure)
</Info>

## PHP

**Library**: [phpredis](https://github.com/phpredis/phpredis)

```php
<?php

$redis = new Redis();

$redis->connect("YOUR_ENDPOINT", "YOUR_PORT");
$redis->auth("YOUR_PASSWORD");

$redis->set("foo", "bar");

print_r($redis->get("foo"));
```

<Info>
  Phpredis supports connection level retries through `OPT_MAX_RETRIES`. However,
  for command level retries, it only supports [SCAN
  command](https://github.com/phpredis/phpredis?tab=readme-ov-file#example-29).
</Info>

## Go

**Library**: [redigo](https://github.com/gomodule/redigo)

```go
func main() {
  c, err := redis.Dial("tcp", "YOUR_ENDPOINT:YOUR_PORT", redis.DialUseTLS(true))
  if err != nil {
      panic(err)
  }

_, err = c.Do("AUTH", "YOUR_PASSWORD")
  if err != nil {
      panic(err)
  }

_, err = c.Do("SET", "foo", "bar")
  if err != nil {
      panic(err)
  }

value, err := redis.String(c.Do("GET", "foo"))
  if err != nil {
      panic(err)
  }

println(value)
}
```

# Connect with @upstash/redis
Source: https://upstash.com/docs/redis/howto/connect-with-upstash-redis

[@upstash/redis](https://github.com/upstash/redis-js)
is an HTTP/REST based Redis client built on top of
[Upstash REST API](/docs/redis/features/restapi). For more information,
refer to the documentation of Upstash redis client ([TypeScript](/docs/redis/sdks/ts/overview) & [Python](/docs/redis/sdks/py/overview)).

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/redis-js/tree/main/examples/cloudflare-workers-with-typescript))
* Fastly Compute@Edge (see
  [the example](https://github.com/upstash/upstash-redis/tree/master/examples/fastly))
* Next.js (see [the quickstart](/docs/redis/quickstarts/nextjs-app-router)), Jamstack
* Client side web/mobile applications
* WebAssembly
* and other environments where HTTP is preferred over TCP.

See
[the list of APIs](https://upstash.com/docs/redis/features/restapi#rest-redis-api-compatibility)
supported.

## Quick Start

### Install

```bash
npm install @upstash/redis
```

### Usage

```typescript
import { Redis } from "@upstash/redis";

const redis = new Redis({
  url: "UPSTASH_REDIS_REST_URL",
  token: "UPSTASH_REDIS_REST_TOKEN",
});

const data = await redis.get("key");
console.log(data);
```

<Tip>
  You can find values to set as `UPSTASH_REDIS_REST_URL` and`UPSTASH_REDIS_REST_TOKEN`
  on the details tab of your database on [Upstash Console](https://console.upstash.com/redis).
  See [Connect Client page](/docs/redis/howto/connect-client#database) for more information.
</Tip>

If you define `UPSTASH_REDIS_REST_URL` and`UPSTASH_REDIS_REST_TOKEN` environment
variables, you can load them automatically.

```typescript
import { Redis } from "@upstash/redis";

const redis = Redis.fromEnv();

const data = await redis.get("key");
console.log(data);
```

# Datadog - Upstash Redis Integration
Source: https://upstash.com/docs/redis/howto/datadog

This guide will walk you through the steps to seamlessly connect your Datadog account with Upstash for enhanced monitoring and analytics.

<Check >
**Integration Scope**

Upstash Datadog Integration only covers Pro databases or those included in the Enterprise Plan.

</Check>

## **Step 1: Log in to Your Datadog Account**

1. Open your web browser and navigate to [Datadog](https://www.datadoghq.com/).
2. Log in to your Datadog account.

## **Step 2: Install Upstash Application**

1. Once logged in, navigate to the "Integrations" page in Datadog.
2. Search for "Upstash" in the integrations list and click on it.

![integration-tab.png]()

Let’s click on the "Install" button to add Upstash to your Datadog account.

![installation.png]()

## **Step 3: Connect Accounts**

After installing Upstash, click on the "Connect Accounts" button and Datadog will redirect you to the Upstash site for account integration.

![connect-acc.png]()

## **Step 4: Select Account to Integrate**

1. On the Upstash site, you will be prompted to select the Datadog account you want to integrate.
2. Choose the appropriate Datadog account from the list.

Upstash Datadog Integration allows you to integrate personal and team based accounts.

**Caveats;**

* This integration can only be executed only one time.If you would like to extend list of the team in integration please re-establish the integration from scratch.

![personal.png]()

![team.png]()

## **Step 5: Wait for Metrics Availability**

Once you've selected your Datadog account, Upstash will begin the integration process and please be patient while the metrics are being retrieved. This may take a few moments.

And here we go, metrics will be available in Upstash Overview Dashboard !

![upstash-dashboard.png]()

## **Step 6: Datadog Integration Removal Process**

Navigate to Integration Tab on your Datadog account,

Once logged in, navigate to the "Integration" tab and continue with Datadog part. If you would like to remove your integration between Upstash and Datadog account press "Remove".

### Confirm Removal:

Upstash will suspend all metric publishing process after the you remove Datadog Integration.

After removing the integration on the Upstash side, it's crucial to go to your Datadog account and remove any related API keys or configurations associated with the integration.

## Pricing

If you choose to integrate Datadog via Upstash, there will be an additional cost of $5 per month.
This charge will be reflected in your monthly invoice accordingly.

## **Conclusion**

Congratulations! You have successfully integrated your Datadog account with Upstash. You will now have access to enhanced monitoring and analytics for your Datadog metrics.

Feel free to explore Upstash's features and dashboards to gain deeper insights into your system's performance.

If you encounter any issues or have questions, please refer to the Upstash support documentation or contact our support team for assistance.

# EMQX - Upstash Redis Integration
Source: https://upstash.com/docs/redis/howto/emqxintegration

EMQX, a robust open-source MQTT message broker, is engineered for scalable, distributed environments, prioritizing high
availability, throughput, and minimal latency. As a preferred protocol in the IoT landscape, MQTT (Message Queuing
Telemetry Transport) excels in enabling devices to effectively publish and subscribe to messages.

Offered by EMQ, EMQX Cloud is a comprehensively managed MQTT service in the cloud, inherently scalable and secure. Its
design is particularly advantageous for IoT applications, providing dependable MQTT messaging services.

This tutorial guides you on streaming MQTT data to Upstash via data integration. It allows clients to send temperature
and humidity data to EMQX Cloud using MQTT and channel it into Upstash for Redis storage.

## Setting Up Redis Database with Upstash

1. Log in and create a Redis Database by clicking the **Create Database** button on [Upstash Console](https://console.upstash.com).

2. Name your database and select a region close to your EMQX Cloud for optimal performance.

3. Click **Create** to have your serverless Redis Database ready.

![upstash]()

### Database Details

Access the database console for the necessary information for further steps.

![upstash]()

The above steps, conclude the initial setup for Upstash.

## Establishing Data Integration with Upstash

### Activating EMQX Cloud's NAT Gateway

1. Log into the EMQX Cloud console and go to the deployment Overview.

2. Select **NAT Gateway** at the bottom and click **Subscribe Now**.

![NAT]()

### Configuring Data Integration

1. In the EMQX Cloud console, choose **Data Integrations** and select **Upstash for Redis**.

![create resource]()

2. Input **Endpoints** info from the Redis detail page into the **Redis Server** field, including the port. Enter the
   password in **Password** and click **Test** to ensure connectivity.
   ![create resource]()

3. Click **New** to add a Redis resource. A new Upstash for Redis will appear under **Configured Resources**.

4. Formulate a new SQL rule in the **SQL** field. This rule will read from `temp_hum/emqx` and append client_id, topic,
   timestamp.

* `up_timestamp`: Message report time
    * `client_id`: Publishing client's ID
    * `temp`: Temperature data
    * `Hum`: Humidity data

```sql
SELECT
timestamp as up_timestamp,
clientid as client_id,
payload.temp as temp,
payload.hum as hum
FROM
"temp_hum/emqx"
```

![rule sql]()

5. Execute an SQL test with payload, topic, client info. Successful results confirm the rule's effectiveness.

![rule sql]()

6. Proceed to **Next** to link an action. The rule will store the timestamp, client ID, temperature, and humidity in
   Redis. Click **Confirm**.

```bash
   HMSET ${client_id} ${up_timestamp} ${temp}
   ```

![rule sql]()

7. Post-binding, click **View Details** for the rule SQL and bound actions.

8. To review rules, select **View Created Rules** in Data Integrations. Check detailed metrics in the **Monitor**
   column.

## Testing the Data Bridge

1. Simulate temperature and humidity data with [MQTTX](https://mqttx.app/). Add connection address and client
   authentication for the EMQX Dashboard.
   ![MQTTX]()

2. In Upstash Console, under Data Browser, select a client entry to review messages.

![monitor]()

# Get Started with AWS Lambda
Source: https://upstash.com/docs/redis/howto/getstartedawslambda

You can connect to Upstash database from your Lambda functions using your
favorite Redis client. You do not need any extra configuration. The only thing
to note is you should use the same region for your Lambda function and database
to minimize latency.

If you do not have any experience with AWS Lambda functions, you can follow the
following tutorial. The tutorial explains the required steps to implement an AWS
Lambda function that takes the key/value as parameters from APIGateway then
inserts an entry (key/value) to the database which is on Upstash. We have
implemented the function in Node.js, but the steps and the logic are quite
similar in other languages.

<Note>
  This example uses Redis clients. If you expect many concurrent AWS Lambda
  invocation then we recommend using
  **[upstash-redis](/docs/redis/howto/connect-with-upstash-redis)** which is HTTP/REST
  based.
</Note>

**Step 1: Create database on Upstash**

If you do not have one, create a database following this
[guide](../overall/getstarted).

**Step 2: Create a Node project**

Create an empty folder for your project and inside the folder create a node
project with the command:

```
npm init
```

Then install the redis client with:

```
npm install ioredis
```

Now create index.js file. Replace the Redis URL in the below code.

<Note>
  This example uses ioredis, you can copy the connection string from the
  **Node** tab in the console.
</Note>

```javascript
var Redis = require("ioredis");

if (typeof client === "undefined") {
  var client = new Redis("rediss://:YOUR_PASSWORD@YOUR_ENDPOINT:YOUR_PORT");
}
exports.handler = async (event) => {
  await client.set("foo", "bar");
  let result = await client.get("foo");
  let response = {
    statusCode: 200,
    body: JSON.stringify({
      result: result,
    }),
  };
  return response;
};
```

**Step 3: Deploy Your Function**

Our function is ready to deploy. Normally you could copy-paste your function
code to AWS Lambda editor. But here it is not possible because we have an extra
dependency (redis-client). So we will zip and upload our function.

When you are in your project folder, create a zip with this command:

```
zip -r app.zip .
```

Now open your AWS console, from the top-right menu, select the region that you
created your database in Upstash. Then find or search the lambda service, click
on `Create Function` button.

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.

<Info>
  See [the blog post](https://blog.upstash.com/serverless-database-connections)
  about the database connections in serverless functions.
</Info>

Below is our findings about various Redis clients' behaviours when connection is
created, a single command is submitted and then connection is closed. **Note
that these commands (AUTH, INFO, PING, QUIT, COMMAND) are not billed.**

| Client                                                | #Commands |  Issued Commands   |
| ----------------------------------------------------- | :-------: | :----------------: |
| [redis-cli](https://redis.io/topics/rediscli)         |     2     |   AUTH - COMMAND   |
| [node-redis](https://github.com/NodeRedis/node-redis) |     3     | AUTH - INFO - QUIT |
| [ioredis](https://github.com/luin/ioredis)            |     3     | AUTH - INFO - QUIT |
| [redis-py](https://github.com/andymccurdy/redis-py)   |     1     |        AUTH        |
| [jedis](https://github.com/xetorthio/jedis)           |     2     |    AUTH - QUIT     |
| [lettuce](https://github.com/lettuce-io/lettuce-core) |     2     |    AUTH - QUIT     |
| [go-redis](https://github.com/go-redis/redis)         |     1     |        AUTH        |

# Get Started with Cloudflare Workers
Source: https://upstash.com/docs/redis/howto/getstartedcloudflareworkers

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.

See
[the code](https://github.com/upstash/examples/tree/master/examples/using-cloudflare-workers).

### 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.

### Step-1: Create Redis Database

Create a free Global database from
[Upstash Console](https://console.upstash.com). Find your REST URL and token in
the database details page in the console. Copy them.

Connect your database with redis-cli and add some greetings

```shell
usw1-selected-termite-30690.upstash.io:30690> set GB "Ey up?"
OK
usw1-selected-termite-30690.upstash.io:30690> set US "Yo, what’s up?"
OK
usw1-selected-termite-30690.upstash.io:30690> set TR "Naber dostum?"
OK
usw1-selected-termite-30690.upstash.io:30690> set DE "Was ist los?"
```

### Step-2: Edge Function

The best way to work with Cloudflare Workers is to use
[Wrangler](https://developers.cloudflare.com/workers/get-started/guide). After
installing and configuring wrangler, create a folder for your project inside the
folder run: `wrangler init`

Choose `yes` to create package.json, `no` to typescript and `yes` to create a
worker in src/index.js.

It will create `wrangler.toml`, `package.json` and `src/index.js`.

Append the Upstash REST URL and token to the toml as below:

```toml
# wrangler.toml

# existing config

[vars]
UPSTASH_REDIS_REST_TOKEN = "AX_sASQgODM5ZjExZGEtMmI3Mi00Mjcwk3NDIxMmEwNmNkYjVmOGVmZTk5MzQ="
UPSTASH_REDIS_REST_URL = "https://us1-merry-macaque-31458.upstash.io/"
```

Install upstash-redis: `npm install @upstash/redis`

Replace `src/index.js` with the following:

```javascript
// src/index.js

import { Redis } from "@upstash/redis/cloudflare";

export default {
  async fetch(request, env) {
    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 correct greeting for that location using the Redis
REST API.

## Run locally

Run `wrangler dev` and open your browser at
[localhost:8787](http://localhost:8787).

## Build and Deploy

Build and deploy your app to Cloudflare by running: `wrangler publish`

The url of your app will be logged:
[https://using-cloudflare-workers.upstash.workers.dev/](https://using-cloudflare-workers.upstash.workers.dev/)

## Typescript example

We also have a typescript example, available
[here](https://github.com/upstash/upstash-redis/tree/main/examples/cloudflare-workers-with-typescript).

# Get Started with Google Cloud Functions
Source: https://upstash.com/docs/redis/howto/getstartedgooglecloudfunctions

### Prerequisites:

* A GCP account for Google Cloud functions.
* Install [Google Cloud SDK](https://cloud.google.com/sdk/docs/install).
* An Upstash account for Serverless Redis.

### Step 1: Init the Project

* Create a folder, then run `npm init` inside the folder.

### Step 2: Install a Redis Client

Our only dependency is redis client. Install go-redis via `npm install ioredis`

### Step 3: Create a Redis Database

Create a Redis database from Upstash console. **Select the GCP US-Central-1 as
the region.** 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

Create index.js as below:

```javascript
var Redis = require("ioredis");

if (typeof client === "undefined") {
  var client = new Redis("rediss://:YOUR_PASSWORD@YOUR_ENDPOINT:YOUR_PORT");
}

exports.helloGET = async (req, res) => {
  let count = await client.incr("counter");
  res.send("Page view:" + count);
};
```

<Note>
  This example uses ioredis, you can copy the connection string from the
  **Node** tab in the console.
</Note>

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. Deploy via:

```shell
gcloud functions deploy helloGET \
--runtime nodejs14 --trigger-http --allow-unauthenticated
```

You will see the URL of your Cloud Function. Click to the URL to check if it is
working properly.

```shell
httpsTrigger:
securityLevel: SECURE_OPTIONAL
url: https://us-central1-functions-317005.cloudfunctions.net/helloGET
```

In case of an issue, you can check the logs of your Cloud Function in the GCP
console as below.

# Import/Export Data
Source: https://upstash.com/docs/redis/howto/importexport

## Importing Data

You can import data into your Upstash Redis database from two sources: an existing backup or an RDB file.

<Warning>
  All existing data in the target database will be deleted before the import operation begins.
</Warning>

### Start an Import

To begin importing data:

* Go to the [Redis database list page](https://console.upstash.com/redis) in the Upstash console
* Click on the `Import...` button

You'll see a dialog with two import options:

### Option 1: Import from Backup

Import data from a backup of any existing database in your account or team:

* Select `From Backup` as the source
* Choose the source database (the database from which the backup was created)
* Select the backup you want to import from
* Select the target database (the database you want to import into)
* Click `Start Import`

### Option 2: Import from RDB File

Import data from an external Redis database by uploading an RDB file:

* Select `From RDB File` as the source
* Click `Upload RDB File` and select your RDB file
* Select the target database (the database you want to import into)
* Click `Start Import`

<Info>
  If you're importing from an external Redis database (from another provider or on-premise), you'll need to export it as an RDB file first.
</Info>

## Exporting Data

You'll be able to export your Upstash Redis database as an RDB file for backup or migration purposes.

### Request an Export

To export your database:

* Go to the database details page and navigate to the `Backups` tab
* Click on the `Backup & Export` button
* Choose `Export`

Your database will be exported as an RDB file. Once you start the export, you'll see the export progress in the backups table.

### Download Your Export

Once the export completes, you'll see a `Download` button in the backups table:

* Find your export in the backups table
* Click the `Download` button to download the RDB file

<Info>
  Not all Redis data structures are included in RDB exports. Notably, Redis Functions data will not be available in the export.
</Info>

# ioredis note
Source: https://upstash.com/docs/redis/howto/ioredisnote

<Note>
  This example uses ioredis, you can copy the connection string from the `Node`
  tab in the console.
</Note>

# Use IP Allowlist
Source: https://upstash.com/docs/redis/howto/ipallowlist

<Info>
  IP Allowlist is available on all plans except for the free plan.
</Info>

IP Allowlist can be used to restrict which IP addresses are permitted to access your database by comparing a connection's address with predefined CIDR blocks. This feature enhances database security by allowing connections only from specified IP addresses. For example if you have dedicated production servers with static IP addresses, enabling IP allowlist blocks connections from other addresses.

![allowlist]()

## Enabling IP Allowlist
By default, any IP address can be used to connect to your database. You must add at least one IP range to enable the allowlist. You can manage added IP ranges in the `Configuration` section on the database details page. You can either provide
* IPv4 address, e.g. `37.237.15.43`
* CIDR block, e.g. `181.49.172.0/24`
<Info>
  Currently, IP Allowlist only supports IPv4 addresses.
</Info>

You can use more than one range to allow multiple clients. Meeting the criteria of just one is enough to establish a connection.

<Note>
  It may take a few minutes for changes to propagate.
</Note>

# Listen Keyspace Notifications
Source: https://upstash.com/docs/redis/howto/keyspacenotifications

Upstash allows you to listen for keyspace notifications over pubsub channels to
receive events for changes over the keys.

For each event that occurs, two kinds of events are fired over the corresponding
pubsub channels:

* A keyspace event that will use the pubsub channel for the key, possibly containing
  other events for the same key
* A keyevent event that will use the pubsub channel for the event, possibly containing
  other events for the different keys

The channel names and their content are of the form:

* `__keyspace@0__:keyname` channel with the values of the event names for the keyspace
  notifications
* `__keyevent@0__:eventname` channel with the values of the key names for the keyevent
  notifications

## Enabling Notifications

By default, all keyspace and keyevent notifications are off. To enable it, you can use
the `CONFIG SET` command, and set the `notify-keyspace-events` options to one of the
appropriate flags described below.

<Warning>
Each keyspace and keyevent notification fired might have an effect on the latency of the
commands as the events are delivered to the listening clients and cluster members for
multi-replica deployments. Therefore, it is advised to only enable the minimal subset of the
notifications that are needed.
</Warning>

| Flag | Description |
| ---- | ----------- |
| K | Keyspace events |
| E | Keyevent events |
| g | Generic command events |
| $ | String command events |
| l | List command events |
| s | Set command events |
| h | Hash command events |
| z | Sorted set command events |
| t | Stream command events |
| d | Module(JSON) command events |
| x | Expiration events |
| e | Eviction events |
| m | Key miss events |
| n | New key events |
| A | Alias for g$lshztxed |

At least one of the `K` or `E` flags must be present in the option value.

For example, you can use the following command to receive keyspace notifications
only for the hash commands:

<Tabs>

<Tab title="cURL">
```bash
curl -X POST \
    -d '["CONFIG", "SET", "notify-keyspace-events", "Kh"]' \
    -H "Authorization: Bearer $UPSTASH_REDIS_REST_TOKEN" \
    $UPSTASH_REDIS_REST_URL
```
</Tab>

<Tab title="redis-cli">
```bash
redis-cli --tls -u $UPSTASH_REDIS_CLI_URL config set notify-keyspace-events Kh
```
</Tab>

</Tabs>

You can listen for all the channels using redis-cli to test the effect of the
above command:

```bash
redis-cli --tls -u $UPSTASH_REDIS_CLI_URL --csv psubscribe '__key*__:*'
```

### Disabling Notifications

You can reuse the `CONFIG SET` command and set `notify-keyspace-events` option to empty string
to disable all keyspace and keyevent notifications.

<Tabs>

<Tab title="cURL">
```bash
curl -X POST \
    -d '["CONFIG", "SET", "notify-keyspace-events", ""]' \
    -H "Authorization: Bearer $UPSTASH_REDIS_REST_TOKEN" \
    $UPSTASH_REDIS_REST_URL
```
</Tab>

<Tab title="redis-cli">
```bash
redis-cli --tls -u $UPSTASH_REDIS_CLI_URL config set notify-keyspace-events ""
```
</Tab>

</Tabs>

### Checking Notification Configuration

`CONFIG GET` command can be used the get the current value of the `notify-keyspace-events` option
to see the active keyspace and keyevent notifications configuration.

<Tabs>

<Tab title="cURL">
```bash
curl -X POST \
    -d '["CONFIG", "GET", "notify-keyspace-events"]' \
    -H "Authorization: Bearer $UPSTASH_REDIS_REST_TOKEN" \
    $UPSTASH_REDIS_REST_URL
```
</Tab>

<Tab title="redis-cli">
```bash
redis-cli --tls -u $UPSTASH_REDIS_CLI_URL config get notify-keyspace-events
```
</Tab>

</Tabs>

# Metrics and Charts
Source: https://upstash.com/docs/redis/howto/metrics-and-charts

The Upstash Console exposes metrics in two places: the database list, and the detail page of a single database. This page explains what each chart shows.

## Database List

The list view aggregates summary information across all of your databases.

Click a database name to open its detail page. For each row the list shows:

* The region of the database
* The plan of the database (free, pay-as-you-go, fixed, or enterprise)

## Database Details

By clicking on a database on the list page, you can navigate to its detail page.

The charts on this page show metrics that are specific to the selected database.

### Current Month

Daily cost of the database for the current billing month.

### Daily Request

Total number of requests per day, over the last 5 days.

## Database Usage

If you click on the "Usage" tab, you can see more detailed charts about the usage of your database.

### 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](/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 (included with Prod pack) and HIPAA (included with Enterprise) 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)

<Warning>
     Please make sure destination database has enough storage space for your data size, and upgrade if needed.
   </Warning>

## Migration Process

You can migrate your data without leaving Upstash Console:

<Warning>
     If you are using ACL, please note that they are not migrated automatically. You need to redefine ACL users for new the global database after migration.
   </Warning>

1. Create a backup of your regional database:
   * Go to your regional database details page
   * Navigate to the `Backups` tab
   * Click the `Backup` button
   * Provide a unique name for your backup
   * Wait for the backup process to complete

<Info>
     During a backup operation, certain administrative operations will be temporarily unavailable: Backup operations, database config changes, plan and region setup, transferring database.
     Regular Redis commands (GET, SET, etc.) are not blocked and continue to work normally.
   </Info>

2. Restore the backup to your global database:
   * Go to your new global database's details page
   * Navigate to the `Backups` tab
   * Click `Restore...`
   * Select your regional database as the source
   * Select the backup you created
   * Click `Start Restore`

<Warning>
     The restore operation will flush (delete) all existing data in your (destination) global database before restoring the backup.
   </Warning>

## Verification

After migration, verify your data:

1. Compare key counts in both databases
2. Sample test some keys to ensure data integrity

## Post-Migration Steps

1. Update your application configuration to use the new Global database URL
2. Test your application thoroughly with the new database
3. Monitor performance and consistency across regions
4. Keep the regional database as backup for a few days
5. Once verified, you can safely delete the regional database

## Need Help?

If you encounter any issues during migration, please contact Upstash support via chat, support@upstash.com or visit our Discord community for assistance.

# Monitor your usage
Source: https://upstash.com/docs/redis/howto/monitoryourusage

We support the Redis `MONITOR` command, a debugging command that allows you to see all requests processed by your Redis instance in real-time.

## Monitoring Your Usage - Video Guide

In this video, we'll walk through setting up a monitor instance step-by-step.

<Note>
  The `MONITOR`command expects a persistent connection and, therefore, does not work over HTTP.
</Note>

In this video, we use `ioredis` to connect to our Upstash Redis database. Using an event handler, we can define what should happen for each executed command against on Redis instance. For example, logging all data to the console.

<RequestExample>
```ts Example
const monitor = await redis.monitor()

monitor.on("monitor", (time, args, source, database) => {
  console.log(time, args, source, database)
})
```
</RequestExample>

# Read Your Writes
Source: https://upstash.com/docs/redis/howto/readyourwrites

The "Read Your Writes" feature in Upstash Redis ensures that write operations are completed before subsequent read operations occur, maintaining data consistency in your application.

### How It Works

All write operations happen on the primary member and take time to propagate to the read replicas. Imagine that a client attempts to read an item immediately after it’s written. The read may go to a replica that hasn’t synced with the primary yet, resulting in stale data being returned.

RYW consistency solves this by returning a **sync token** after each request, which indicates the primary member’s state. In the next request, this sync token ensures the read replica syncs up to that token before serving the read.

So, the sync token acts as a checkpoint, ensuring that any read operations following a write reflect the most recent changes, even if they are served by a read replica.

Management of the sync token is handled automatically by the official [Typescript (version 1.34.0 and later)](/docs/redis/sdks/ts/overview) and [Python (version 1.2.0 and later)](/docs/redis/sdks/py/overview) SDKs of Upstash. When you initialize a Redis client with these SDKs, the writes made by that client will be respected during subsequent reads from the same client.

For REST users, you can achieve similar behavior by using the `upstash-sync-token` header. Each time you make a request, save the value of the `upstash-sync-token` header from the response and pass it in the `upstash-sync-token` header of your next request. This ensures that subsequent reads reflect the writes.

### Cross-Client Synchronization

Imagine that you are writing some key to Redis and then you read the same key from a different Redis client instance. In this case, the second client’s read request may not reflect the write made by the first client, as the sync tokens are updated independently in the two clients.

Consider these two example functions, each representing separate API endpoints:

```ts
export const writeRequest = async () => {
  const redis = Redis.fromEnv();
  const randomKey = nanoid();
  await redis.set(randomKey, "value");
  return randomKey;
};

export const readRequest = async (randomKey: string) => {
  const redis = Redis.fromEnv();
  const value = await redis.get(randomKey);
  return value;
};
```

If these functions are called in sequence, they will create two separate clients:

```ts
const randomKey = await writeRequest();
await readRequest(randomKey);
```

As explained above, in rare cases, one of your [read replicas](/docs/redis/features/globaldatabase#primary-region-and-read-regions) can serve the `read` request before it receives the `write` update from the primary replica. To avoid this, if you are using `@upstash/redis` version 1.34.1 or later, you can pass the `readYourWritesSyncToken` from the first client to the second:

```ts
export const writeRequest = async () => {
  const redis = Redis.fromEnv();
  const randomKey = nanoid();
  await redis.set(randomKey, "value");

// Get the token **after** making the write
  const token = redis.readYourWritesSyncToken;
  return { randomKey, token };
};

export const readRequest = async (
  randomKey: string,
  token: string | undefined
) => {
  const redis = Redis.fromEnv();

// Set the token **before** making the read
  redis.readYourWritesSyncToken = token;

const value = await redis.get(randomKey);
  return value;
};

const { randomKey, token } = await writeRequest();
await readRequest(randomKey, token);
```

Remember to get the sync token after the write request is completed, as the session token changes with each request.

For REST users or the Upstash Python SDK, a similar approach can be used. In Python, use `Redis._sync_token` instead of `readYourWritesSyncToken`.

# Terraform Provider
Source: https://upstash.com/docs/redis/howto/terraformprovider

You can use Upstash terraform provider to create your resources. API key is
required in order to create resources.

### Configure Provider

Provider requires your email address and api key which can be created in
console.

```tf
provider "upstash" {
  email = ""
  api_key = ""
}
```

### Create Database

As input you need to give database name, region and type.

```tf
resource "upstash_database" "mydb" {
  database_name = "testdblstr"
  region = "eu-west-1"
  type = "free"
}
```

You can output database credentials as following

```tf
output "endpoint" {
  value = "${upstash_database.mydb.endpoint}"
}

output "port" {
  value = "${upstash_database.mydb.port}"
}
output "password" {
  value = "${upstash_database.mydb.password}"
}
```

See our
[Terraform Provider Github Repository](https://github.com/upstash/terraform-provider-upstash)
for details and examples about Upstash Terraform Provider.

# Upgrade Your Database
Source: https://upstash.com/docs/redis/howto/upgrade-database

The free tier has limits on monthly commands, data size, and the number of databases per account. See the [pricing page](https://upstash.com/pricing/redis) for the current values.

If your database is close to any of these limits, upgrade to the pay-as-you-go plan, which removes the daily request cap and raises the data size ceiling.

To upgrade, you need a payment method. Follow the steps in [Add a Payment Method](/docs/common/account/add-payment-method). Once a payment method is added, your database switches automatically to the pay-as-you-go plan.

See [Pricing & Limits](../overall/pricing) for the full breakdown of the pay-as-you-go and Fixed plans. If your workload will exceed those quotas, reach out at support@upstash.com about our [Enterprise Plan](../overall/enterprise) where the limits are configurable.

<Note>
  During the upgrade process, you will not lose any data but your database will
  experience a downtime about 1-2 seconds. Your existing clients will be
  disconnected. So it is recommended to upgrade your database when there is the
  least activity.
</Note>

# Vercel - Upstash Redis Integration
Source: https://upstash.com/docs/redis/howto/vercelintegration

If you are using [Vercel](https://vercel.com/) then you can integrate Upstash
Redis, Vector, Search or QStash to your project easily. Upstash is the perfect serverless
solution for your applications thanks to its:

* Low latency data
* Per request pricing
* Durable storage
* Ease of use

Below are the steps of the integration.

## Add Integration to Your Vercel Account

Visit the [Upstash Integration](https://vercel.com/integrations/upstash) on
Vercel and click the `Install` button. If you are installing an Upstash integration
for the first time, you will be prompted to choosing between connecting an existing Upstash
account or letting Vercel manage an Upstash account for you.

In both cases, you will be able to create and use a redis database as usual. If you let Vercel
manage your Upstash account, you can handle payments, database creation and deletion directly from the Vercel dashboard.

If you choose to connect an existing Upstash account, you will be able to utilize features on Upstash Console
such as teams and audit logs.

### Option 1: "Create New Upstash Account"

If you choose this option, Vercel will prompt you to choose one of the products available on Upstash,
configure the database (by choosing database name, regions, plan). After you finish the configuration,
Vercel will create the Upstash account and the selected resources for you and redirect you to the
page of the created resource on Vercel dashboard.

On the Vercel dashboard, you will be able to find the credentials of the database, change the database
name, update the regions or plan.
<img width="520" />

You can also go to the `Settings` tab and connect your apps on Vercel to the database, making the credentials
of the database available to the app as environment variables.

### Option 2: "Link Existing Upstash Account"

Vercel will redirect you to Upstash, where you can select your Vercel project
and Upstash resources that you want to integrate.

<Tip>
  You should login to [the Upstash Console](https://console.upstash.com/) with your account if you
  are not logged in before clicking continue.
</Tip>

If you do not have a Redis database yet, you can create one
from the dropdown menu.

Once you have selected all resources, click the `Save` 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.

<Tip>
  You need to redeploy your app for the environment variable to be used.
</Tip>

The [Integration Dashboard](https://console.upstash.com/integration/vercel)
allows you to see all your integrations, link new projects or manage existing
ones.

<img />

## Use Upstash in Your App

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
import { Redis } from "@upstash/redis";
import { type NextRequest, NextResponse } from "next/server";

const redis = Redis.fromEnv();

export const POST = async (request: NextRequest) => {
  await redis.set("foo", "bar");
  const bar = await redis.get("foo");
  return NextResponse.json({
    body: `foo: ${bar}`,
  });
}
```

### QStash

**Client**

```ts
import { Client } from "@upstash/qstash";

const client = new Client({
  token: process.env.QSTASH_TOKEN,
});

const res = await client.publishJSON({
  url: "https://my-api...",
  body: {
    hello: "world",
  },
});
```

**Receiver**

```ts
import { Receiver } from "@upstash/qstash";

const receiver = new Receiver({
  currentSigningKey: process.env.QSTASH_CURRENT_SIGNING_KEY,
  nextSigningKey: process.env.QSTASH_NEXT_SIGNING_KEY,
});

const isValid = await receiver.verify({
  signature: "..."
  body: "..."
})
```

### Vector

```ts
import { Index } from "@upstash/vector";

const index = new Index({
  url: process.env.UPSTASH_VECTOR_REST_URL,
  token: process.env.UPSTASH_VECTOR_REST_TOKEN,
});

await index.upsert({
  id: "1",
  data: "Hello world!",
  metadata: { "category": "greeting" }
})
```

### Search

```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");
await index.upsert({
  id: "1",
  content: { text: "Hello world!" },
  metadata: { category: "greeting" }
});
```

## 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](/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=<YOUR_HOST>
export UPSTASH_REDIS_PORT=<YOUR_PORT>
export UPSTASH_REDIS_PASSWORD=<YOUR_PASSWORD>
```

You can also use `python-dotenv` to load environment variables from a `.env` file:

```text .env
UPSTASH_REDIS_HOST=<YOUR_HOST>
UPSTASH_REDIS_PORT=<YOUR_PORT>
UPSTASH_REDIS_PASSWORD=<YOUR_PASSWORD
```

## Example Application

### Setting up Celery with Upstash Redis

```python tasks.py
import os
from celery import Celery
from dotenv import load_dotenv

load_dotenv()

# Configure Celery with Upstash Redis
UPSTASH_REDIS_HOST = os.getenv("UPSTASH_REDIS_HOST")
UPSTASH_REDIS_PORT = os.getenv("UPSTASH_REDIS_PORT")
UPSTASH_REDIS_PASSWORD = os.getenv("UPSTASH_REDIS_PASSWORD")

connection_link = f"rediss://:{UPSTASH_REDIS_PASSWORD}@{UPSTASH_REDIS_HOST}:{UPSTASH_REDIS_PORT}?ssl_cert_reqs=required"

celery_app = Celery("tasks", broker=connection_link, backend=connection_link)

@celery_app.task
def add(x, y):
    return x + y
```

Note that we should use the `rediss://` protocol to connect to redis over TLS and set `ssl_cert_reqs=required` to enforce certificate validation.

### Running the Worker

Start the Celery worker to execute tasks:

```bash
celery -A tasks worker --loglevel=info
```

### Using the Task

You can now use the `add` task to perform background computations:

```python main.py
from tasks import add

result = add.delay(4, 6)
print(f"Task state: {result.state}")  # Outputs 'PENDING' initially

# Wait for the result
output = result.get(timeout=10)
print(f"Task result: {output}")  # Outputs '10'
```

## Billing Optimization

Celery workers poll Redis continuously, 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 [our Fixed plans](/docs/redis/overall/pricing#all-plans-and-limits), **we recommend switching to a Fixed plan to avoid increased command count and high costs in Celery use cases.**

## Conclusion

To see a more detailed example of using Celery with Upstash Redis, check out the [Job Processor with Celery example](https://upstash.com/examples/jobprocessorwithcelery) on our website.

For more details on Celery, visit the [Celery Documentation](https://docs.celeryproject.org). For Upstash Redis, check out the [Upstash Redis Documentation](/docs/redis).

# DrizzleORM with Upstash Redis
Source: https://upstash.com/docs/redis/integrations/drizzle

### Quickstart

DrizzleORM provides an `upstashCache()` helper to easily connect with Upstash Redis. To prevent surprises, the cache is always opt-in by default. Nothing is cached until you opt-in for a specific query or enable global caching.

First, install the drizzle package:

```bash
npm install drizzle-orm
```

**Configure your Drizzle instance:**
```ts
import { upstashCache } from "drizzle-orm/cache/upstash"
import { drizzle } from "drizzle-orm/..."

const db = drizzle(process.env.DB_URL!, {
  cache: upstashCache(),
})
```

You can also explicitly define your Upstash credentials, enable global caching for all queries by default (opt-out) or pass custom caching options:

```ts
import { upstashCache } from "drizzle-orm/cache/upstash"
import { drizzle } from "drizzle-orm/..."

const db = drizzle(process.env.DB_URL!, {
  cache: upstashCache({
    // 👇 Redis credentials (optional — can also be pulled from env vars)
    url: "<UPSTASH_URL>",
    token: "<UPSTASH_TOKEN>",
    // 👇 Enable caching for all queries (optional, default false)
    global: true,
    // 👇 Default cache behavior (optional)
    config: { ex: 60 },
  }),
})
```

***

### Cache Behavior

* **Per-query caching (opt-in, default):**
  No queries are cached unless you explicitly call `.$withCache()`.

```ts
  await db.insert(users).value({ email: "cacheman@upstash.com" });

// 👇 reads from cache
  await db.select().from(users).$withCache()
  ```

* **Global caching:**
  When setting `global: true`, all queries will read from cache by default.

```ts
  const db = drizzle(process.env.DB_URL!, {
    cache: upstashCache({ global: true }),
  })

// 👇 reads from cache (no more explicit `$withCache()`)
  await db.select().from(users)
  ```

You can always turn off caching for a specific query:

```ts
  await db.select().from(users).$withCache(false)
  ```

***

### Manual Cache Invalidation

Cache invalidation is fully automatic by default. If you ever need to, you can manually invalidate cached queries by table name or custom tags:

```ts
// 👇 invalidate all queries that use the `users` table
await db.$cache?.invalidate({ tables: ["usersTable"] })

// 👇 invalidate all queries by custom tag (defined in previous queries)
await db.$cache?.invalidate({ tags: ["custom_key"] })
```

***

For more details on this integration, refer to the [Drizzle ORM caching documentation](https://cache.drizzle-orm-fe.pages.dev/docs/cache).

# Upstash MCP
Source: https://upstash.com/docs/redis/integrations/mcp

# n8n with Upstash Redis
Source: https://upstash.com/docs/redis/integrations/n8n

## Quickstart

In this quickstart we're going to set up an Redis node in n8n using Upstash Redis, and go over an example use case step by step.

***

### Step 1: Get Your Upstash Redis Credentials

1. Go to Upstash Console and create a Redis database if you don't have any
2. Note down your credentials in the details page, we will be using those to connect Redis
   Node in n8n to our Upstash Redis instance.
   <img />

***

### Step 2: Set Up an n8n Project

1. Go to https://n8n.io and create a new project
2. Create a Trigger as Webhook with default settings, this will be our entry point. Our Redis instances gonna watch the visits to this url.
   <img />

***

### Step 3: Create a Redis Node

Now, Let's create a redis node and connect it to our Upstash Redis instance

1. Search for redis in nodes, and select increment action.
   <img />
2. In the opening window, click select credentials, and create new credentials.
   Later, for other redis nodes, this will be saved and used automatically.
   <img />
3. Fill the credentials.

* Pass your Upstash Token to the password field.
   * Leave the user field blank
   * Pass your Upstash Redis endpoint to the host field. (Leave the https:// part out)
   * If your Upstash Database has a port other than the default 6379, change it here.

<img />

4. Enable SSL (Upstash Redis requires SSL) and hit the save button.
   <img />

***

### Redis Example: Store the Visit Count per Visitor

1. Track the users with `x-real-ip`
   <img />
2. Add another redis node with get action to see the visit counts
   <img />
3. Read the set visit count with redis get
   <img />

***

### Test Redis Example

Run the workflow and visit the webhook URL, This will send a get request and trigger the workflow run.
Then from the headers your ip will be fetched and in the redis instance you will see `user:user-ip` set to `1`.
As you visit the page it will be incremented and at the end of the workflow you can track and confirm this setup with
the get request.

***

# Prometheus - Upstash Redis Integration
Source: https://upstash.com/docs/redis/integrations/prometheus

To monitor your Upstash database in Prometheus and visualize metrics in Grafana, follow these steps:

<Check >
**Integration Scope**

Upstash Prometheus Integration only covers Pro databases or those included in the Enterprise Plan.

</Check>

## **Step 1: Log in to Your Upstash Account**

1. Open your web browser and navigate to [Upstash](https://console.upstash.com/).
2. Navigate to the main dashboard, where you’ll see a list of your databases.

## **Step 2: Select your Database**

1. Select the database you want to integrate with Prometheus.
2. This will open the database settings, where you can manage various configuration options for your selected database.

![configuration.png]()

3. Enable Prometheus by toggling the switch. This allows you to monitor metrics related to your Upstash database performance, usage, and other key metrics.

## **Step 3: Connect Accounts**

1. After enabling Prometheus, a monitoring token is generated and displayed.

2. Copy this token. This token is unique to your database and is required to authenticate Prometheus with the Upstash metrics endpoint.

<Check >
**Header Format**

You should add monitoring token according to this format `Bearer <MONITORING_TOKEN>`

</Check>

![monitoring-token.png]()

## **Step 4: Set Up Prometheus Connection**
### **Grafana Dashboard Setup**

1. Open your Grafana instance, navigate to the Data Sources section, and select Prometheus as the data source.

![datasource.png]()

2. Enter the data source name, set `https://api.upstash.com/monitoring/prometheus` as the data source address, and then add your monitoring token in the HTTP Headers section.

![headers.png]()

3. Then, click <b>Test and Save</b> to verify that the data source is working properly.

![datasource-final.png]()

### **Prometheus Federation Setup**
Federation lets your Prometheus pull metrics from Upstash’s API and store them in **your own** Prometheus instance, so Grafana can query your Prometheus instead of hitting the Upstash endpoint directly.
#### When to use federation
* You already run Prometheus and want to persist Upstash metrics locally.
* You want to control retention, recording rules, or alerts on Upstash metrics

1. Set up a new scrape job in your Prometheus configuration file (`prometheus.yml`):
```yaml
scrape_configs:
  # Federation job: pull from Upstash API
  - job_name: "federate_upstash"
    honor_labels: true
    metrics_path: "/monitoring/prometheus/federate"
    scheme: https
    params:
      match[]:
        - 'upstash_db_metrics{}'
    static_configs:
      - targets:
          - "api.upstash.com"
    authorization:
      type: Bearer
      credentials: "<MONITORING_TOKEN>"
```
<Check>
This configuration assumes you want to pull all metrics. You can adjust the `match[]` parameter to filter specific metrics if needed.
* `upstash_db_metrics{database_id="your_database_id"}` can be used to pull metrics for a specific database
* `upstash_db_metrics{replica_id=~"us-east-1.*"}` can be used to pull metrics for replicas in a specific region
</Check>

2. Verify the Federation Target
* Reload (or restart) your Prometheus server to apply the new configuration.
* Visit **Prometheus → Status → Targets** and confirm `federate_upstash` is **UP**

## **Step 5: Wait for Metrics Availability**

To visualize your Upstash metrics, you can use a pre-built Grafana dashboard.

Select your Prometheus data source when prompted, and complete the import.

Please check this address to access Upstash Grafana Dashboard <a href="https://grafana.com/grafana/dashboards/22257-upstash-redis-dashboard/"> Dashboard </a>

![grafana-dashboard.png]()

## **Conclusion**

You've now integrated your database with Upstash Prometheus, providing access to improved monitoring and analytics.

Feel free to explore Upstash's features and dashboards to gain deeper insights into your system's performance.

If you encounter any issues or have questions, please refer to the Upstash support documentation or contact our support team for assistance.

# Configure Upstash Ratelimit Strapi Plugin
Source: https://upstash.com/docs/redis/integrations/ratelimit/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

<ParamField path="enabled" type="boolean" default="true">
  Enable or disable the plugin.
</ParamField>

## Database Configurations

<ParamField path="token" type="string" required>
  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`
</ParamField>
<ParamField path="url" type="string" required>
  The URL for the Upstash Redis REST API. You can find this credential on
  Upstash Console with the name `UPSTASH_REDIS_REST_URL`
</ParamField>

<ParamField path="prefix" type="string" default="@strapi">
  The prefix for the rate limit keys. The plugin uses this prefix to store the
  rate limit data in Redis. <br />
  For example, if the prefix is `@strapi`, the key will be
  `@strapi:<method>:<route>:<identifier>`.
</ParamField>

<ParamField path="analytics" type="boolean" default="false">
  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).
</ParamField>

## Strategy

The plugin uses a strategy array to define the rate limits per route. Each strategy object has the following properties:

<ParamField path="path" type="string" required>
  The path to apply the rate limit. You can use wildcards to match multiple
  routes. For example, `*` matches all routes. <br />
  Some examples: <br />
  * `path: "/api/restaurants/:id"` <br />
  * `path: "/api/restaurants"` <br />
</ParamField>

<ParamField path="identifierSource" type="string" required>
  The source to identifiy the user. Requests with the same identifier will be
  rate limited under the same limit. <br />
  Available sources are: <br />
  * `ip`: The IP address of the user. <br />
  * `header`: The value of a header key. You should pass the source in the `header.<HEADER_KEY>` format. <br />
  For example, `header.Authorization` will use the value of the `Authorization`
</ParamField>

<ParamField path="debug" type="string">
  Enable debug mode for the route. When enabled, the plugin logs the remaining
  limits and the block status for each request. <br />
</ParamField>

<ParamField path="limiter" type="object" required>
  The limiter configuration for the route. The limiter object has the following
  properties:

<Card>
	  <ParamField path="algorithm" type="'fixed-window' | 'sliding-window' | 'token-bucket'" required>
		The rate limit algorithm to use. For more information related to algorithms, see docs [**here**](/docs/redis/sdks/ratelimit-ts/algorithms). <br />
		* `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. <br />
		* `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. <br />
		* `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.<br />
	  </ParamField>
	  <ParamField path="tokens" type="number" required>
	  	The number of tokens allowed in the time window. <br />
	  </ParamField>
	  <ParamField path="window" type="string" required>
	  	The time window for the rate limit. Available units are `"ms" | "s" | "m" | "h" | "d"` <br />
	  	For example, `20s` means 20 seconds.
	  </ParamField>
	  <ParamField path="refillRate" type="number">
	  	The rate at which the bucket refills. **This property is only used for the token-bucket algorithm.** <br />
	  </ParamField>
  </Card>
</ParamField>

## Examples

<CodeGroup>
```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"
    }
  }
}
```

</CodeGroup>

# Upstash Ratelimit Strapi Integration
Source: https://upstash.com/docs/redis/integrations/ratelimit/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
```

</CodeGroup>

### Create database

Create a new redis database on [Upstash Console](https://console.upstash.com/). See [related docs](/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="<YOUR_TOKEN>"
UPSTASH_REDIS_REST_URL="<YOUR_URL>"
```

### Configure the plugin

You can use

<CodeGroup>
```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",
    },
  },
});
```

</CodeGroup>

# Replit Templates
Source: https://upstash.com/docs/redis/integrations/replit-templates

## Overview

Explore our collection of example templates showcasing Upstash's capabilities with different frameworks and use cases. Each template comes with a live demo and source code on Replit.

<CardGroup cols={2}>
  <Card
    title="Redis Web Caching"
    icon="database"
    href="https://upstash-web-caching.replit.app"
  >
    Cache SQL queries using Upstash Redis to speed up read requests
  </Card>
  <Card
    title="Rate Limiting Dashboard"
    icon="gauge-high"
    href="https://rate-limit-dashboard.replit.app"
  >
    Implement robust rate limiting using Upstash Redis in a web application
  </Card>
  <Card
    title="Real-time Chat"
    icon="messages"
    href="https://real-time-chat.replit.app"
  >
    Build a real-time chat application using Upstash Redis Pub/Sub with Python
  </Card>
  <Card
    title="RAG Chat Application"
    icon="robot"
    href="https://upstash-rag-chat.replit.app"
  >
    Create an AI chat app with context retrieval using Upstash Vector and Redis
  </Card>
  <Card
    title="Vector Search"
    icon="magnifying-glass"
    href="https://upstash-vector-search.replit.app"
  >
    Implement powerful web search using Upstash Vector Hybrid Search
  </Card>
</CardGroup>

# Sidekiq with Upstash Redis
Source: https://upstash.com/docs/redis/integrations/sidekiq

You can use Sidekiq with Upstash Redis. Sidekiq is a Ruby based queue library with a Redis-based queue storage so you can use with Upstash Redis.

## Example Application

```bash
bundle init
bundle add sidekiq
```

```python
require "sidekiq"
require "sidekiq/api"

connection_url = ENV['UPSTASH_REDIS_LINK']

Sidekiq.configure_client do |config|
    config.redis = {url: connection_url}
end

Sidekiq.configure_server do |config|
    config.redis = {url: connection_url}
end

class EmailService
    include Sidekiq::Worker
    def perform(id, type)
        # Logic goes here. Let's assume sending email by printing to console.
        puts "Emailed to: " +  id + ": " + "'Congrats on " + type + " plan.'"
    end
end

def updateEmail(id, newType)
    jobFound = false

a = Sidekiq::ScheduledSet.new
    a.each do |job|
        if job.args[0] == id
            job.delete
            jobFound = true
        end
    end

if jobFound
        EmailService.perform_async(id, ("starting using our service and upgrading it to " + newType))
    else
        EmailService.perform_async(id, ("upgrading to " + newType))
    end
end

def sendEmail(id, type)
    case type
    when "free"
        # if free, delay for 10 seconds.
        EmailService.perform_in("10", id, "free")
    when "paid"
        # if paid, delay for 5 seconds.
        EmailService.perform_in("5", id, "paid")
    when "enterprise"
        # if enterprise, immediately queue.
        EmailService.perform_async(id, "enterprise")
    when "enterprise10k"
        EmailService.perform_async(id, "enterprise10k")
    else
        puts "Only plans are: `free`, `paid` and `enterprise`"
    end
end

def clearSchedules()
    Sidekiq::ScheduledSet.new.clear
    Sidekiq::Queue.new.clear
end
```

## Billing Optimization
Sidekiq 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](/docs/redis/overall/pricing#all-plans-and-limits), **we recommend switching to a Fixed plan to avoid increased command count and high costs in Sidekiq use cases.**

# Changelog
Source: https://upstash.com/docs/redis/overall/changelog

<Update label="March 2026">
Added [Upstash Redis Search](/docs/redis/search/introduction) feature, a new extension for searching Redis data. It works with JSON, Hash, and String data, automatically keeps indexes in sync with Redis writes, and supports full-text search, filtering, aggregations, aliases, highlighting, fuzzy matching, phrase queries, and regex matching.

Redis Search is available through the [@upstash/redis](/docs/redis/sdks/ts/overview) and [upstash-redis](/docs/redis/sdks/py/overview) SDKs. If you already use `node-redis` or `ioredis`, you can use the [`@upstash/search-redis`](/docs/redis/search/adapters/node-redis) and [`@upstash/search-ioredis`](/docs/redis/search/adapters/ioredis) wrappers without switching clients.

New Redis Search commands:
* [`SEARCH.CREATE`](/docs/redis/search/command-reference#searchcreate): Create a search index
* [`SEARCH.DROP`](/docs/redis/search/command-reference#searchdrop): Remove a search index
* [`SEARCH.DESCRIBE`](/docs/redis/search/command-reference#searchdescribe): Return metadata about a search index
* [`SEARCH.WAITINDEXING`](/docs/redis/search/command-reference#searchwaitindexing): Wait until pending index updates are visible to queries
* [`SEARCH.QUERY`](/docs/redis/search/command-reference#searchquery): Search documents with a JSON filter
* [`SEARCH.COUNT`](/docs/redis/search/command-reference#searchcount): Count matching documents without returning them
* [`SEARCH.AGGREGATE`](/docs/redis/search/command-reference#searchaggregate): Compute analytics over matching documents
* [`SEARCH.ALIASADD`](/docs/redis/search/command-reference#searchaliasadd), [`SEARCH.ALIASDEL`](/docs/redis/search/command-reference#searchaliasdel), and [`SEARCH.LISTALIASES`](/docs/redis/search/command-reference#searchlistaliases): Manage search index aliases
</Update>

<Update label="December 2025">
Added [Redis Functions](https://redis.io/docs/latest/develop/programmability/functions-intro/) support. New commands are:
* [`FCALL`](https://redis.io/docs/latest/commands/fcall/): Call a function with read/write capabilities
* [`FCALL_RO`](https://redis.io/docs/latest/commands/fcall_ro/): Call a function in read-only mode
* `FUNCTION DELETE`, `FUNCTION FLUSH`, `FUNCTION KILL`, `FUNCTION LIST`, `FUNCTION LOAD` and `FUNCTION STATS`

New Hash commands:
* [`HGETDEL`](https://redis.io/docs/latest/commands/hgetdel/): Get and delete hash fields atomically
* [`HGETEX`](https://redis.io/docs/latest/commands/hgetex/): Get hash fields with expiration support
* [`HSETEX`](https://redis.io/docs/latest/commands/hsetex/): Set hash fields with expiration support

New Stream Commands:
* [`XDELEX`](https://redis.io/docs/latest/commands/xdelex/): Extended delete for streams
* [`XACKDEL`](https://redis.io/docs/latest/commands/xackdel/): Acknowledge and delete stream entries

New Bit operations added:
* `BITOP DIFF`: A bit is set only if it's set in all source bitmaps
* `BITOP DIFF1`: A bit is set if it's set in the first key but not in any of the other keys
* `BITOP ANDOR`: A bit is set if it's set in X and also in one or more of Y1, Y2, ...
* `BITOP ONE`: A bit is set if it's set in exactly one source key
</Update>

<Update label="April 2025">
Added HASH expiration support. New commands are:
* [`HEXPIRE`](https://redis.io/docs/latest/commands/hexpire/): Set expiration time in seconds
* [`HPEXPIRE`](https://redis.io/docs/latest/commands/hpexpire/): Set expiration time in milliseconds
* [`HEXPIREAT`](https://redis.io/docs/latest/commands/hexpireat/): Set expiration time as Unix timestamp in seconds
* [`HPEXPIREAT`](https://redis.io/docs/latest/commands/hpexpireat/): Set expiration time as Unix timestamp in milliseconds
* [`HTTL`](https://redis.io/docs/latest/commands/httl/): Get remaining time to live in seconds
* [`HPTTL`](https://redis.io/docs/latest/commands/hpttl/): Get remaining time to live in milliseconds
* [`HEXPIRETIME`](https://redis.io/docs/latest/commands/hexpiretime/): Get absolute expiration time as Unix timestamp in seconds
* [`HPEXPIRETIME`](https://redis.io/docs/latest/commands/hpexpiretime/): Get absolute expiration time as Unix timestamp in milliseconds
* [`HPERSIST`](https://redis.io/docs/latest/commands/hpersist/): Remove expiration from hash fields
</Update>

<Update label="Feb 2025">
Added [`EVAL_RO`](https://redis.io/docs/latest/commands/eval_ro/) and [`EVALSHA_RO`](https://redis.io/docs/latest/commands/evalsha_ro/)
commands introduced in Redis 7.
</Update>

<Update label="July 2024">
* Added REST API support for [`MONITOR`](https://redis.io/docs/latest/commands/monitor/) and [`SUBSCRIBE`](https://redis.io/docs/latest/commands/subscribe/)
commands using [SSE](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events).
See [Monitor](../features/restapi#monitor-command) and [Subscribe](../features/restapi#subscribe-command) docs.
* Added [`JSON.MSET`](https://redis.io/docs/latest/commands/json.mset/) and [`JSON.MERGE`](https://redis.io/docs/latest/commands/json.merge/) commands.
* Introduced the `IP Allowlist` feature for enhanced security on newly created databases. By default, all IP addresses will be allowed.
However, access can be restricted by specifying permitted IP addresses or CIDR ranges.
</Update>

<Update label="June 2024">
* Added AWS AP-NorthEast-1 Japan region.
* Added an option to return REST response in [`RESP2`](https://redis.io/docs/latest/develop/reference/protocol-spec/) format instead of `JSON`.
See [REST API docs](/docs/redis/features/restapi#resp2-format-responses) for more information.
</Update>

<Update label="April 2024">
* Implemented [`MONITOR`](https://redis.io/docs/latest/commands/monitor/) command
* Implemented Redis [keyspace notifications](/docs/redis/howto/keyspacenotifications)
* Implemented [`WAIT`](https://redis.io/docs/latest/commands/wait/) and [`WAITAOF`](https://redis.io/docs/latest/commands/waitaof/) commands
* Added `lag` field to [`XINFO GROUPS`](https://redis.io/docs/latest/commands/xinfo-groups/)
* Added [`CLIENT ID`](https://redis.io/docs/latest/commands/client-id/) subcommand
* Added password strength check to [`ACL SETUSER`](https://redis.io/docs/latest/commands/acl-setuser/) command
</Update>

<Update label="February 2024">
* Fixed JSON commands with empty keys
* Fixed a panic on `XTRIM` and `XDEL`
* Added `CLIENT SETNAME/NAME/LIST` subcommands
* Implemented near exact trim for streams
</Update>

<Update label="September 2023">
* Implemented some missing Redis commands:
    * `DUMP`
    * `RESTORE`
    * `ZMPOP`
    * `BZMPOP`
    * `LMPOP`
    * `BLMPOP`
    * `SINTERCARD`
* Added support for `BIT/BYTE` flag to `BITPOS` and `BITCOUNT` commands
* Added support for `XX`, `NX`, `GT`, and `LT` arguments to `EXPIRE` commands
* Allowed `NX` and `GET` args to be used together in `SET` command
</Update>

# Compare
Source: https://upstash.com/docs/redis/overall/compare

In this section, we will compare Upstash with alternative cloud based solutions.

## AWS ElastiCache

* **Serverless Pricing:** Elasticache does not have a serverless pricing model.
  The price does not scale to zero. You need to pay for the instances even when
  you do not use them. Upstash charges per request.
* **REST API:** Unlike ElastiCache, Upstash has a built-in REST API, so you can
  access from environments where TCP connections are not allowed such as edge
  functions at Cloudflare Workers.
* **Access:** Elasticache is designed to be used inside AWS VPC. You can access
  Upstash from anywhere.
* **Durability:** Upstash persists your data to the block storage in addition to
  memory so you can use it as your primary database.

## AWS MemoryDB

* **Serverless Pricing:** Similar to Elasticache, MemoryDB does not offer a
  serverless pricing model. The pricing does not scale down to zero, and even
  the most affordable instance costs over \$200 per month. This means you are
  required to pay for the instances regardless of usage. In contrast, Upstash
  follows a different approach by charging per request. With Upstash, you only
  incur charges when actively using your Redis database, ensuring that you do
  not have to pay when it's not in use.

* **REST API:** Unlike MemoryDB, Upstash has a built-in REST API, so you can
  access from environments where TCP connections are not allowed such as edge
  functions at Cloudflare Workers.

* **Access:** MemoryDB is designed to be used inside AWS VPC. You can access
  Upstash from anywhere.

## Redis Labs

* **Serverless Pricing:** Redis Labs does not have a serverless pricing model
  either. The price does not scale to zero. You need to pay for the instances
  even when you do not use them. Upstash charges per request, so you only pay
  for your real usage.
* **REST API:** Unlike Redis Labs, Upstash has a built-in REST API, so you can
  access from environments where TCP connections are not allowed such as edge
  functions at Cloudflare Workers.
* **Durability:** Upstash persists your data to the block storage instantly in
  addition to the memory, so you can use it as your primary database.
* **Full-text search:** Upstash offers [Upstash Redis Search](/docs/redis/search/introduction), a fast
  Tantivy-based full-text search extension that works with JSON, Hashes, and Strings out of the box
  and stays automatically in sync as you write.
* **JSON:** Upstash supports the `JSON.*` commands natively. See [compatibility](/docs/redis/overall/compatibility).

## AWS DynamoDB

* **Latency:** DynamoDB is a disk based data storage. Both write and read
  latency are much higher than Redis. Check our
  [benchmark app](https://serverless-battleground.vercel.app/) to get an idea.

* **Complex Pricing:** Initially, DynamoDB may appear cost-effective, but if you
  begin utilizing advanced features such as DAX or Global Tables, you might
  encounter unexpected expenses on your AWS bill. In contrast, Upstash offers a
  more transparent pricing policy, ensuring that you are not taken by surprise.
  With Upstash, you can optionally set a budget to cap your maximum costs,
  providing clarity and preventing any unwelcome surprises in your billing.

* **Portability:** DynamoDB is exclusive to AWS and cannot be used outside of
  the AWS platform. However, Redis is supported by numerous cloud providers and
  can also be self-hosted. Upstash provides compatibility with Redis, ensuring
  vendor neutrality.

* **Testability:** Running a local Redis for testing purposes is much easier
  than running a local DynamoDB. Check
  [this](https://stackoverflow.com/questions/26901613/easier-dynamodb-local-testing).

## FaunaDB

* **Latency:** FaunaDB is a globally consistent database. Consistency at global
  level comes with performance cost. Check our
  [benchmark app](https://serverless-battleground.vercel.app/) to get an idea.

* **Complex Pricing:** FaunaDB has a complicated pricing. It has 6 different
  dimensions to calculate the price. Check
  [this article](https://docs.fauna.com/fauna/current/manage/plans-billing/billing/)
  where the pricing is explained. If your use case is write heavy and
  if your requests have bigger payloads, then it can become expensive very easily.
  On the other hand, Upstash has different options for different needs and
  pricing is simple for all options. You pay per request in addition to
  storage cost which is generally much smaller amount.

* **Portability:** FaunaDB is only supported by Fauna Inc. On the other hand,
  you can use Redis almost in all cloud providers as well as you can host Redis
  yourself. Upstash does not lock you to any vendor.

* **Testability:** Running a local Redis for testing purposes is much easier
  than running a local FaunaDB. Check
  [this](https://dev.to/englishcraig/how-to-set-up-faunadb-for-local-development-5ha7).

## What makes Upstash different?

You have a new project and you do not know how many requests will it receive?
You love the performance and simplicity of Redis. But all Redis Cloud services
charge you per instance or per GB of memory. But maybe your application will not
receive big traffic at first, then why will you pay the full amount?
Unfortunately none of the current Redis cloud products provides a real
`pay-per-use` pricing model.

Let's do a simple calculation. Say I have a 1GB Redis database and I receive 1
million requests per month. For ElastiCache (cache.t3.small, \$0.034 hourly) this
costs at least \$24 not including data transfer and storage cost. For RedisLabs,
the 1GB plan costs \$22 per month. For Upstash the price is \$0.2 per 100k
requests. For 1 million, it is \$2 plus the storage cost that is \$0.25. So for
1GB, 1M request per months, ElastiCache is \$24, RedisLabs is \$22, Upstash is
$2.25.

<img />

**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
the option to switch to a [Fixed plan](/docs/redis/overall/pricing). On a Fixed plan you set a
fixed price per month with a restriction on max throughput and data size. For high and
steady throughput use cases, Fixed plans cost less than pay-as-you-go.
The good thing is you can start your database with pay-as-you-go pricing and
move to a Fixed plan when you want. See [pricing](/docs/redis/overall/pricing) and [enterprise plans](/docs/redis/overall/enterprise) for more information.

Even if you choose not to upgrade to a Fixed plan, Upstash gives you control
over your spending through optional budgets. By default, there is no monthly
price ceiling on a pay-as-you-go database, but you can set a budget to cap
your costs. When a database hits its configured budget, its operations are
stopped, ensuring you never exceed the amount you've set.

# Redis® API Compatibility: supported commands, modules, and protocols
Source: https://upstash.com/docs/redis/overall/compatibility

<Note>
  Upstash supports both native Redis TCP and HTTPS REST.
</Note>

Upstash supports Redis client protocol up to version `8.2`. We are also gradually adding changes introduced in later versions.

Most of the unsupported items are in our roadmap. If you need a feature that we do not support, please drop a note to [support@upstash.com](mailto:support@upstash.com).
So we can inform you when we are planning to support it.

***

## Supported Commands

<Accordion title="Bitmap" icon="grid">
<CardGroup cols={2}>
<Card title="BITCOUNT" href="https://redis.io/docs/latest/commands/bitcount/">Count set bits in a string</Card>
<Card title="BITFIELD" href="https://redis.io/docs/latest/commands/bitfield/">Perform arbitrary bitfield operations</Card>
<Card title="BITFIELD_RO" href="https://redis.io/docs/latest/commands/bitfield_ro/">Read-only bitfield operations</Card>
<Card title="BITOP" href="https://redis.io/docs/latest/commands/bitop/">Perform bitwise operations between strings</Card>
<Card title="BITPOS" href="https://redis.io/docs/latest/commands/bitpos/">Find first bit set or clear in a string</Card>
<Card title="GETBIT" href="https://redis.io/docs/latest/commands/getbit/">Get the bit value at offset</Card>
<Card title="SETBIT" href="https://redis.io/docs/latest/commands/setbit/">Set or clear the bit at offset</Card>
</CardGroup>
</Accordion>

<Accordion title="Connection" icon="plug">
<CardGroup cols={2}>
<Card title="AUTH" href="https://redis.io/docs/latest/commands/auth/">Authenticate to the server</Card>
<Card title="CLIENT GETNAME" href="https://redis.io/docs/latest/commands/client-getname/">Get the current connection name</Card>
<Card title="CLIENT ID" href="https://redis.io/docs/latest/commands/client-id/">Get the current client ID</Card>
<Card title="CLIENT INFO" href="https://redis.io/docs/latest/commands/client-info/">Get info about current connection</Card>
<Card title="CLIENT LIST" href="https://redis.io/docs/latest/commands/client-list/">List all client connections</Card>
<Card title="CLIENT SETINFO" href="https://redis.io/docs/latest/commands/client-setinfo/">Set client connection attributes</Card>
<Card title="CLIENT SETNAME" href="https://redis.io/docs/latest/commands/client-setname/">Set the connection name</Card>
<Card title="ECHO" href="https://redis.io/docs/latest/commands/echo/">Echo the given string</Card>
<Card title="HELLO" href="https://redis.io/docs/latest/commands/hello/">Handshake with Redis protocol</Card>
<Card title="PING" href="https://redis.io/docs/latest/commands/ping/">Ping the server</Card>
<Card title="QUIT" href="https://redis.io/docs/latest/commands/quit/">Close the connection</Card>
<Card title="RESET" href="https://redis.io/docs/latest/commands/reset/">Reset the connection</Card>
<Card title="SELECT" href="https://redis.io/docs/latest/commands/select/">Select the database by index</Card>
</CardGroup>
</Accordion>

<Accordion title="Functions" icon="code">
<CardGroup cols={2}>
<Card title="FCALL" href="https://redis.io/docs/latest/commands/fcall/">Call a function</Card>
<Card title="FCALL_RO" href="https://redis.io/docs/latest/commands/fcall_ro/">Call a read-only function</Card>
<Card title="FUNCTION DELETE" href="https://redis.io/docs/latest/commands/function-delete/">Delete a library</Card>
<Card title="FUNCTION FLUSH" href="https://redis.io/docs/latest/commands/function-flush/">Delete all libraries</Card>
<Card title="FUNCTION KILL" href="https://redis.io/docs/latest/commands/function-kill/">Kill a running function</Card>
<Card title="FUNCTION LIST" href="https://redis.io/docs/latest/commands/function-list/">List all libraries</Card>
<Card title="FUNCTION LOAD" href="https://redis.io/docs/latest/commands/function-load/">Load a library</Card>
<Card title="FUNCTION STATS" href="https://redis.io/docs/latest/commands/function-stats/">Get function execution stats</Card>
</CardGroup>
</Accordion>

<Accordion title="Generic" icon="sliders">
<CardGroup cols={2}>
<Card title="COPY" href="https://redis.io/docs/latest/commands/copy/">Copy a key to another key</Card>
<Card title="DEL" href="https://redis.io/docs/latest/commands/del/">Delete one or more keys</Card>
<Card title="DUMP" href="https://redis.io/docs/latest/commands/dump/">Serialize a key's value</Card>
<Card title="EXISTS" href="https://redis.io/docs/latest/commands/exists/">Check if keys exist</Card>
<Card title="EXPIRE" href="https://redis.io/docs/latest/commands/expire/">Set a key's TTL in seconds</Card>
<Card title="EXPIREAT" href="https://redis.io/docs/latest/commands/expireat/">Set expiry as Unix timestamp</Card>
<Card title="EXPIRETIME" href="https://redis.io/docs/latest/commands/expiretime/">Get expiry as Unix timestamp</Card>
<Card title="KEYS" href="https://redis.io/docs/latest/commands/keys/">Find keys matching a pattern</Card>
<Card title="PERSIST" href="https://redis.io/docs/latest/commands/persist/">Remove the expiration from a key</Card>
<Card title="PEXPIRE" href="https://redis.io/docs/latest/commands/pexpire/">Set a key's TTL in milliseconds</Card>
<Card title="PEXPIREAT" href="https://redis.io/docs/latest/commands/pexpireat/">Set expiry as Unix ms timestamp</Card>
<Card title="PEXPIRETIME" href="https://redis.io/docs/latest/commands/pexpiretime/">Get expiry as Unix ms timestamp</Card>
<Card title="PTTL" href="https://redis.io/docs/latest/commands/pttl/">Get TTL in milliseconds</Card>
<Card title="RANDOMKEY" href="https://redis.io/docs/latest/commands/randomkey/">Return a random key</Card>
<Card title="RENAME" href="https://redis.io/docs/latest/commands/rename/">Rename a key</Card>
<Card title="RENAMENX" href="https://redis.io/docs/latest/commands/renamenx/">Rename a key if new key doesn't exist</Card>
<Card title="RESTORE" href="https://redis.io/docs/latest/commands/restore/">Deserialize and restore a key</Card>
<Card title="SCAN" href="https://redis.io/docs/latest/commands/scan/">Incrementally iterate keys</Card>
<Card title="TOUCH" href="https://redis.io/docs/latest/commands/touch/">Update last access time of keys</Card>
<Card title="TTL" href="https://redis.io/docs/latest/commands/ttl/">Get TTL in seconds</Card>
<Card title="TYPE" href="https://redis.io/docs/latest/commands/type/">Get the type of a key</Card>
<Card title="UNLINK" href="https://redis.io/docs/latest/commands/unlink/">Delete keys asynchronously</Card>
</CardGroup>
</Accordion>

<Accordion title="Geo" icon="location-dot">
<CardGroup cols={2}>
<Card title="GEOADD" href="https://redis.io/docs/latest/commands/geoadd/">Add geospatial items</Card>
<Card title="GEODIST" href="https://redis.io/docs/latest/commands/geodist/">Get distance between two members</Card>
<Card title="GEOHASH" href="https://redis.io/docs/latest/commands/geohash/">Get geohash strings for members</Card>
<Card title="GEOPOS" href="https://redis.io/docs/latest/commands/geopos/">Get coordinates of members</Card>
<Card title="GEORADIUS" href="https://redis.io/docs/latest/commands/georadius/">Query members within radius</Card>
<Card title="GEORADIUS_RO" href="https://redis.io/docs/latest/commands/georadius_ro/">Read-only radius query</Card>
<Card title="GEORADIUSBYMEMBER" href="https://redis.io/docs/latest/commands/georadiusbymember/">Radius query centered on member</Card>
<Card title="GEORADIUSBYMEMBER_RO" href="https://redis.io/docs/latest/commands/georadiusbymember_ro/">Read-only radius query by member</Card>
<Card title="GEOSEARCH" href="https://redis.io/docs/latest/commands/geosearch/">Search for members in an area</Card>
<Card title="GEOSEARCHSTORE" href="https://redis.io/docs/latest/commands/geosearchstore/">Store geosearch results</Card>
</CardGroup>
</Accordion>

<Accordion title="Hash" icon="hashtag">
<CardGroup cols={2}>
<Card title="HDEL" href="https://redis.io/docs/latest/commands/hdel/">Delete one or more hash fields</Card>
<Card title="HEXISTS" href="https://redis.io/docs/latest/commands/hexists/">Check if a hash field exists</Card>
<Card title="HEXPIRE" href="https://redis.io/docs/latest/commands/hexpire/">Set field TTL in seconds</Card>
<Card title="HEXPIREAT" href="https://redis.io/docs/latest/commands/hexpireat/">Set field expiry as timestamp</Card>
<Card title="HEXPIRETIME" href="https://redis.io/docs/latest/commands/hexpiretime/">Get field expiry as timestamp</Card>
<Card title="HGET" href="https://redis.io/docs/latest/commands/hget/">Get the value of a hash field</Card>
<Card title="HGETALL" href="https://redis.io/docs/latest/commands/hgetall/">Get all fields and values</Card>
<Card title="HGETDEL" href="https://redis.io/docs/latest/commands/hgetdel/">Get and delete hash fields</Card>
<Card title="HGETEX" href="https://redis.io/docs/latest/commands/hgetex/">Get fields and set their expiry</Card>
<Card title="HINCRBY" href="https://redis.io/docs/latest/commands/hincrby/">Increment integer value of a field</Card>
<Card title="HINCRBYFLOAT" href="https://redis.io/docs/latest/commands/hincrbyfloat/">Increment float value of a field</Card>
<Card title="HKEYS" href="https://redis.io/docs/latest/commands/hkeys/">Get all fields in a hash</Card>
<Card title="HLEN" href="https://redis.io/docs/latest/commands/hlen/">Get number of fields in a hash</Card>
<Card title="HMGET" href="https://redis.io/docs/latest/commands/hmget/">Get values of multiple fields</Card>
<Card title="HMSET" href="https://redis.io/docs/latest/commands/hmset/">Set multiple hash fields</Card>
<Card title="HPERSIST" href="https://redis.io/docs/latest/commands/hpersist/">Remove field expiration</Card>
<Card title="HPEXPIRE" href="https://redis.io/docs/latest/commands/hpexpire/">Set field TTL in milliseconds</Card>
<Card title="HPEXPIREAT" href="https://redis.io/docs/latest/commands/hpexpireat/">Set field expiry as ms timestamp</Card>
<Card title="HPEXPIRETIME" href="https://redis.io/docs/latest/commands/hpexpiretime/">Get field expiry as ms timestamp</Card>
<Card title="HPTTL" href="https://redis.io/docs/latest/commands/hpttl/">Get field TTL in milliseconds</Card>
<Card title="HRANDFIELD" href="https://redis.io/docs/latest/commands/hrandfield/">Get random fields from a hash</Card>
<Card title="HSCAN" href="https://redis.io/docs/latest/commands/hscan/">Incrementally iterate hash fields</Card>
<Card title="HSET" href="https://redis.io/docs/latest/commands/hset/">Set hash field values</Card>
<Card title="HSETEX" href="https://redis.io/docs/latest/commands/hsetex/">Set fields with expiration</Card>
<Card title="HSETNX" href="https://redis.io/docs/latest/commands/hsetnx/">Set field only if it doesn't exist</Card>
<Card title="HSTRLEN" href="https://redis.io/docs/latest/commands/hstrlen/">Get length of a field's value</Card>
<Card title="HTTL" href="https://redis.io/docs/latest/commands/httl/">Get field TTL in seconds</Card>
<Card title="HVALS" href="https://redis.io/docs/latest/commands/hvals/">Get all values in a hash</Card>
</CardGroup>
</Accordion>

<Accordion title="HyperLogLog" icon="chart-simple">
<CardGroup cols={2}>
<Card title="PFADD" href="https://redis.io/docs/latest/commands/pfadd/">Add elements to HyperLogLog</Card>
<Card title="PFCOUNT" href="https://redis.io/docs/latest/commands/pfcount/">Get estimated cardinality</Card>
<Card title="PFMERGE" href="https://redis.io/docs/latest/commands/pfmerge/">Merge multiple HyperLogLogs</Card>
</CardGroup>
</Accordion>

<Accordion title="JSON" icon="brackets-curly">
To query inside JSON values (full-text, fuzzy, phrase, regex), see [Upstash Redis Search](/docs/redis/search/introduction).

<CardGroup cols={2}>
<Card title="JSON.ARRAPPEND" href="https://redis.io/docs/latest/commands/json.arrappend/">Append values to JSON array</Card>
<Card title="JSON.ARRINDEX" href="https://redis.io/docs/latest/commands/json.arrindex/">Find index of value in array</Card>
<Card title="JSON.ARRINSERT" href="https://redis.io/docs/latest/commands/json.arrinsert/">Insert values into JSON array</Card>
<Card title="JSON.ARRLEN" href="https://redis.io/docs/latest/commands/json.arrlen/">Get JSON array length</Card>
<Card title="JSON.ARRPOP" href="https://redis.io/docs/latest/commands/json.arrpop/">Pop value from JSON array</Card>
<Card title="JSON.ARRTRIM" href="https://redis.io/docs/latest/commands/json.arrtrim/">Trim JSON array to range</Card>
<Card title="JSON.CLEAR" href="https://redis.io/docs/latest/commands/json.clear/">Clear JSON values</Card>
<Card title="JSON.DEL" href="https://redis.io/docs/latest/commands/json.del/">Delete JSON values</Card>
<Card title="JSON.FORGET" href="https://redis.io/docs/latest/commands/json.forget/">Alias for JSON.DEL</Card>
<Card title="JSON.GET" href="https://redis.io/docs/latest/commands/json.get/">Get JSON values</Card>
<Card title="JSON.MERGE" href="https://redis.io/docs/latest/commands/json.merge/">Merge JSON values</Card>
<Card title="JSON.MGET" href="https://redis.io/docs/latest/commands/json.mget/">Get values from multiple keys</Card>
<Card title="JSON.MSET" href="https://redis.io/docs/latest/commands/json.mset/">Set values in multiple keys</Card>
<Card title="JSON.NUMINCRBY" href="https://redis.io/docs/latest/commands/json.numincrby/">Increment JSON number</Card>
<Card title="JSON.NUMMULTBY" href="https://redis.io/docs/latest/commands/json.nummultby/">Multiply JSON number</Card>
<Card title="JSON.OBJKEYS" href="https://redis.io/docs/latest/commands/json.objkeys/">Get JSON object keys</Card>
<Card title="JSON.OBJLEN" href="https://redis.io/docs/latest/commands/json.objlen/">Get JSON object size</Card>
<Card title="JSON.RESP" href="https://redis.io/docs/latest/commands/json.resp/">Get JSON in RESP format</Card>
<Card title="JSON.SET" href="https://redis.io/docs/latest/commands/json.set/">Set JSON value</Card>
<Card title="JSON.STRAPPEND" href="https://redis.io/docs/latest/commands/json.strappend/">Append to JSON string</Card>
<Card title="JSON.STRLEN" href="https://redis.io/docs/latest/commands/json.strlen/">Get JSON string length</Card>
<Card title="JSON.TOGGLE" href="https://redis.io/docs/latest/commands/json.toggle/">Toggle JSON boolean</Card>
<Card title="JSON.TYPE" href="https://redis.io/docs/latest/commands/json.type/">Get JSON value type</Card>
</CardGroup>
</Accordion>

<Accordion title="List" icon="list">
<CardGroup cols={2}>
<Card title="BLMOVE" href="https://redis.io/docs/latest/commands/blmove/">Blocking list move</Card>
<Card title="BLMPOP" href="https://redis.io/docs/latest/commands/blmpop/">Blocking pop from multiple lists</Card>
<Card title="BLPOP" href="https://redis.io/docs/latest/commands/blpop/">Blocking left pop</Card>
<Card title="BRPOP" href="https://redis.io/docs/latest/commands/brpop/">Blocking right pop</Card>
<Card title="BRPOPLPUSH" href="https://redis.io/docs/latest/commands/brpoplpush/">Blocking pop and push</Card>
<Card title="LINDEX" href="https://redis.io/docs/latest/commands/lindex/">Get element by index</Card>
<Card title="LINSERT" href="https://redis.io/docs/latest/commands/linsert/">Insert before or after pivot</Card>
<Card title="LLEN" href="https://redis.io/docs/latest/commands/llen/">Get list length</Card>
<Card title="LMOVE" href="https://redis.io/docs/latest/commands/lmove/">Move element between lists</Card>
<Card title="LMPOP" href="https://redis.io/docs/latest/commands/lmpop/">Pop from multiple lists</Card>
<Card title="LPOP" href="https://redis.io/docs/latest/commands/lpop/">Pop from list head</Card>
<Card title="LPOS" href="https://redis.io/docs/latest/commands/lpos/">Find element position</Card>
<Card title="LPUSH" href="https://redis.io/docs/latest/commands/lpush/">Push to list head</Card>
<Card title="LPUSHX" href="https://redis.io/docs/latest/commands/lpushx/">Push to head if list exists</Card>
<Card title="LRANGE" href="https://redis.io/docs/latest/commands/lrange/">Get range of elements</Card>
<Card title="LREM" href="https://redis.io/docs/latest/commands/lrem/">Remove elements by value</Card>
<Card title="LSET" href="https://redis.io/docs/latest/commands/lset/">Set element at index</Card>
<Card title="LTRIM" href="https://redis.io/docs/latest/commands/ltrim/">Trim list to range</Card>
<Card title="RPOP" href="https://redis.io/docs/latest/commands/rpop/">Pop from list tail</Card>
<Card title="RPOPLPUSH" href="https://redis.io/docs/latest/commands/rpoplpush/">Pop from tail and push to head</Card>
<Card title="RPUSH" href="https://redis.io/docs/latest/commands/rpush/">Push to list tail</Card>
<Card title="RPUSHX" href="https://redis.io/docs/latest/commands/rpushx/">Push to tail if list exists</Card>
</CardGroup>
</Accordion>

<Accordion title="Pub/Sub" icon="tower-broadcast">
<CardGroup cols={2}>
<Card title="PSUBSCRIBE" href="https://redis.io/docs/latest/commands/psubscribe/">Subscribe to pattern channels</Card>
<Card title="PUBLISH" href="https://redis.io/docs/latest/commands/publish/">Publish message to channel</Card>
<Card title="PUBSUB" href="https://redis.io/docs/latest/commands/pubsub/">Inspect pub/sub state</Card>
<Card title="PUNSUBSCRIBE" href="https://redis.io/docs/latest/commands/punsubscribe/">Unsubscribe from patterns</Card>
<Card title="SUBSCRIBE" href="https://redis.io/docs/latest/commands/subscribe/">Subscribe to channels</Card>
<Card title="UNSUBSCRIBE" href="https://redis.io/docs/latest/commands/unsubscribe/">Unsubscribe from channels</Card>
</CardGroup>
</Accordion>

<Accordion title="Scripting" icon="scroll">
<CardGroup cols={2}>
<Card title="EVAL" href="https://redis.io/docs/latest/commands/eval/">Execute a Lua script</Card>
<Card title="EVAL_RO" href="https://redis.io/docs/latest/commands/eval_ro/">Execute read-only Lua script</Card>
<Card title="EVALSHA" href="https://redis.io/docs/latest/commands/evalsha/">Execute cached Lua script by SHA</Card>
<Card title="EVALSHA_RO" href="https://redis.io/docs/latest/commands/evalsha_ro/">Read-only execute by SHA</Card>
<Card title="SCRIPT EXISTS" href="https://redis.io/docs/latest/commands/script-exists/">Check if scripts exist in cache</Card>
<Card title="SCRIPT FLUSH" href="https://redis.io/docs/latest/commands/script-flush/">Clear the script cache</Card>
<Card title="SCRIPT LOAD" href="https://redis.io/docs/latest/commands/script-load/">Load script into cache</Card>
</CardGroup>
</Accordion>

<Accordion title="Server" icon="server">
<CardGroup cols={2}>
<Card title="ACL" href="https://redis.io/docs/latest/commands/acl/">Manage access control list</Card>
<Card title="DBSIZE" href="https://redis.io/docs/latest/commands/dbsize/">Get number of keys in database</Card>
<Card title="FLUSHALL" href="https://redis.io/docs/latest/commands/flushall/">Delete all keys in all databases</Card>
<Card title="FLUSHDB" href="https://redis.io/docs/latest/commands/flushdb/">Delete all keys in current database</Card>
<Card title="MONITOR" href="https://redis.io/docs/latest/commands/monitor/">Stream all commands received</Card>
<Card title="TIME" href="https://redis.io/docs/latest/commands/time/">Get current server time</Card>
</CardGroup>
</Accordion>

<Accordion title="Set" icon="layer-group">
<CardGroup cols={2}>
<Card title="SADD" href="https://redis.io/docs/latest/commands/sadd/">Add members to a set</Card>
<Card title="SCARD" href="https://redis.io/docs/latest/commands/scard/">Get set cardinality</Card>
<Card title="SDIFF" href="https://redis.io/docs/latest/commands/sdiff/">Get set difference</Card>
<Card title="SDIFFSTORE" href="https://redis.io/docs/latest/commands/sdiffstore/">Store set difference</Card>
<Card title="SINTER" href="https://redis.io/docs/latest/commands/sinter/">Get set intersection</Card>
<Card title="SINTERCARD" href="https://redis.io/docs/latest/commands/sintercard/">Get intersection cardinality</Card>
<Card title="SINTERSTORE" href="https://redis.io/docs/latest/commands/sinterstore/">Store set intersection</Card>
<Card title="SISMEMBER" href="https://redis.io/docs/latest/commands/sismember/">Check if member exists in set</Card>
<Card title="SMEMBERS" href="https://redis.io/docs/latest/commands/smembers/">Get all set members</Card>
<Card title="SMISMEMBER" href="https://redis.io/docs/latest/commands/smismember/">Check multiple members</Card>
<Card title="SMOVE" href="https://redis.io/docs/latest/commands/smove/">Move member between sets</Card>
<Card title="SPOP" href="https://redis.io/docs/latest/commands/spop/">Remove random members</Card>
<Card title="SRANDMEMBER" href="https://redis.io/docs/latest/commands/srandmember/">Get random members</Card>
<Card title="SREM" href="https://redis.io/docs/latest/commands/srem/">Remove members from a set</Card>
<Card title="SSCAN" href="https://redis.io/docs/latest/commands/sscan/">Incrementally iterate set members</Card>
<Card title="SUNION" href="https://redis.io/docs/latest/commands/sunion/">Get set union</Card>
<Card title="SUNIONSTORE" href="https://redis.io/docs/latest/commands/sunionstore/">Store set union</Card>
</CardGroup>
</Accordion>

<Accordion title="Sorted Set" icon="arrow-down-1-9">
<CardGroup cols={2}>
<Card title="BZMPOP" href="https://redis.io/docs/latest/commands/bzmpop/">Blocking pop from sorted sets</Card>
<Card title="BZPOPMAX" href="https://redis.io/docs/latest/commands/bzpopmax/">Blocking pop max score member</Card>
<Card title="BZPOPMIN" href="https://redis.io/docs/latest/commands/bzpopmin/">Blocking pop min score member</Card>
<Card title="ZADD" href="https://redis.io/docs/latest/commands/zadd/">Add members with scores</Card>
<Card title="ZCARD" href="https://redis.io/docs/latest/commands/zcard/">Get sorted set cardinality</Card>
<Card title="ZCOUNT" href="https://redis.io/docs/latest/commands/zcount/">Count members in score range</Card>
<Card title="ZDIFF" href="https://redis.io/docs/latest/commands/zdiff/">Get sorted set difference</Card>
<Card title="ZDIFFSTORE" href="https://redis.io/docs/latest/commands/zdiffstore/">Store sorted set difference</Card>
<Card title="ZINCRBY" href="https://redis.io/docs/latest/commands/zincrby/">Increment member's score</Card>
<Card title="ZINTER" href="https://redis.io/docs/latest/commands/zinter/">Get sorted set intersection</Card>
<Card title="ZINTERCARD" href="https://redis.io/docs/latest/commands/zintercard/">Get intersection cardinality</Card>
<Card title="ZINTERSTORE" href="https://redis.io/docs/latest/commands/zinterstore/">Store sorted set intersection</Card>
<Card title="ZLEXCOUNT" href="https://redis.io/docs/latest/commands/zlexcount/">Count members in lex range</Card>
<Card title="ZMPOP" href="https://redis.io/docs/latest/commands/zmpop/">Pop members from sorted sets</Card>
<Card title="ZMSCORE" href="https://redis.io/docs/latest/commands/zmscore/">Get scores of multiple members</Card>
<Card title="ZPOPMAX" href="https://redis.io/docs/latest/commands/zpopmax/">Pop members with highest scores</Card>
<Card title="ZPOPMIN" href="https://redis.io/docs/latest/commands/zpopmin/">Pop members with lowest scores</Card>
<Card title="ZRANDMEMBER" href="https://redis.io/docs/latest/commands/zrandmember/">Get random members</Card>
<Card title="ZRANGE" href="https://redis.io/docs/latest/commands/zrange/">Get members by index range</Card>
<Card title="ZRANGEBYLEX" href="https://redis.io/docs/latest/commands/zrangebylex/">Get members by lex range</Card>
<Card title="ZRANGEBYSCORE" href="https://redis.io/docs/latest/commands/zrangebyscore/">Get members by score range</Card>
<Card title="ZRANGESTORE" href="https://redis.io/docs/latest/commands/zrangestore/">Store range result</Card>
<Card title="ZRANK" href="https://redis.io/docs/latest/commands/zrank/">Get member's rank</Card>
<Card title="ZREM" href="https://redis.io/docs/latest/commands/zrem/">Remove members</Card>
<Card title="ZREMRANGEBYLEX" href="https://redis.io/docs/latest/commands/zremrangebylex/">Remove members by lex range</Card>
<Card title="ZREMRANGEBYRANK" href="https://redis.io/docs/latest/commands/zremrangebyrank/">Remove members by rank range</Card>
<Card title="ZREMRANGEBYSCORE" href="https://redis.io/docs/latest/commands/zremrangebyscore/">Remove members by score range</Card>
<Card title="ZREVRANGE" href="https://redis.io/docs/latest/commands/zrevrange/">Get members in reverse order</Card>
<Card title="ZREVRANGEBYLEX" href="https://redis.io/docs/latest/commands/zrevrangebylex/">Reverse lex range query</Card>
<Card title="ZREVRANGEBYSCORE" href="https://redis.io/docs/latest/commands/zrevrangebyscore/">Reverse score range query</Card>
<Card title="ZREVRANK" href="https://redis.io/docs/latest/commands/zrevrank/">Get member's reverse rank</Card>
<Card title="ZSCAN" href="https://redis.io/docs/latest/commands/zscan/">Incrementally iterate sorted set</Card>
<Card title="ZSCORE" href="https://redis.io/docs/latest/commands/zscore/">Get member's score</Card>
<Card title="ZUNION" href="https://redis.io/docs/latest/commands/zunion/">Get sorted set union</Card>
<Card title="ZUNIONSTORE" href="https://redis.io/docs/latest/commands/zunionstore/">Store sorted set union</Card>
</CardGroup>
</Accordion>

<Accordion title="Streams" icon="water">
<CardGroup cols={2}>
<Card title="XACK" href="https://redis.io/docs/latest/commands/xack/">Acknowledge stream messages</Card>
<Card title="XACKDEL" href="https://redis.io/docs/latest/commands/xackdel/">Acknowledge and delete messages</Card>
<Card title="XADD" href="https://redis.io/docs/latest/commands/xadd/">Add entry to stream</Card>
<Card title="XAUTOCLAIM" href="https://redis.io/docs/latest/commands/xautoclaim/">Auto-claim idle messages</Card>
<Card title="XCLAIM" href="https://redis.io/docs/latest/commands/xclaim/">Claim pending messages</Card>
<Card title="XDEL" href="https://redis.io/docs/latest/commands/xdel/">Delete stream entries</Card>
<Card title="XDELEX" href="https://redis.io/docs/latest/commands/xdelex/">Delete entries with expiration</Card>
<Card title="XGROUP" href="https://redis.io/docs/latest/commands/xgroup/">Manage consumer groups</Card>
<Card title="XINFO CONSUMERS" href="https://redis.io/docs/latest/commands/xinfo-consumers/">List group consumers</Card>
<Card title="XINFO GROUPS" href="https://redis.io/docs/latest/commands/xinfo-groups/">List stream groups</Card>
<Card title="XINFO STREAM" href="https://redis.io/docs/latest/commands/xinfo-stream/">Get stream info</Card>
<Card title="XLEN" href="https://redis.io/docs/latest/commands/xlen/">Get stream length</Card>
<Card title="XPENDING" href="https://redis.io/docs/latest/commands/xpending/">Get pending messages info</Card>
<Card title="XRANGE" href="https://redis.io/docs/latest/commands/xrange/">Get range of stream entries</Card>
<Card title="XREAD" href="https://redis.io/docs/latest/commands/xread/">Read stream entries</Card>
<Card title="XREADGROUP" href="https://redis.io/docs/latest/commands/xreadgroup/">Read as consumer group</Card>
<Card title="XREVRANGE" href="https://redis.io/docs/latest/commands/xrevrange/">Get range in reverse order</Card>
<Card title="XTRIM" href="https://redis.io/docs/latest/commands/xtrim/">Trim stream to max length</Card>
</CardGroup>
</Accordion>

<Accordion title="String" icon="font">
<CardGroup cols={2}>
<Card title="APPEND" href="https://redis.io/docs/latest/commands/append/">Append value to a string</Card>
<Card title="DECR" href="https://redis.io/docs/latest/commands/decr/">Decrement integer value by 1</Card>
<Card title="DECRBY" href="https://redis.io/docs/latest/commands/decrby/">Decrement integer by amount</Card>
<Card title="GET" href="https://redis.io/docs/latest/commands/get/">Get string value</Card>
<Card title="GETDEL" href="https://redis.io/docs/latest/commands/getdel/">Get value and delete key</Card>
<Card title="GETEX" href="https://redis.io/docs/latest/commands/getex/">Get value and set expiration</Card>
<Card title="GETRANGE" href="https://redis.io/docs/latest/commands/getrange/">Get substring of string</Card>
<Card title="GETSET" href="https://redis.io/docs/latest/commands/getset/">Set value and return old value</Card>
<Card title="INCR" href="https://redis.io/docs/latest/commands/incr/">Increment integer value by 1</Card>
<Card title="INCRBY" href="https://redis.io/docs/latest/commands/incrby/">Increment integer by amount</Card>
<Card title="INCRBYFLOAT" href="https://redis.io/docs/latest/commands/incrbyfloat/">Increment float by amount</Card>
<Card title="MGET" href="https://redis.io/docs/latest/commands/mget/">Get values of multiple keys</Card>
<Card title="MSET" href="https://redis.io/docs/latest/commands/mset/">Set multiple keys at once</Card>
<Card title="MSETNX" href="https://redis.io/docs/latest/commands/msetnx/">Set multiple keys if none exist</Card>
<Card title="PSETEX" href="https://redis.io/docs/latest/commands/psetex/">Set value with ms expiration</Card>
<Card title="SET" href="https://redis.io/docs/latest/commands/set/">Set string value</Card>
<Card title="SETEX" href="https://redis.io/docs/latest/commands/setex/">Set value with expiration</Card>
<Card title="SETNX" href="https://redis.io/docs/latest/commands/setnx/">Set value if key doesn't exist</Card>
<Card title="SETRANGE" href="https://redis.io/docs/latest/commands/setrange/">Overwrite part of string</Card>
<Card title="STRLEN" href="https://redis.io/docs/latest/commands/strlen/">Get string length</Card>
</CardGroup>
</Accordion>

<Accordion title="Transactions" icon="right-left">
<CardGroup cols={2}>
<Card title="DISCARD" href="https://redis.io/docs/latest/commands/discard/">Discard queued commands</Card>
<Card title="EXEC" href="https://redis.io/docs/latest/commands/exec/">Execute queued commands</Card>
<Card title="MULTI" href="https://redis.io/docs/latest/commands/multi/">Start a transaction</Card>
<Card title="UNWATCH" href="https://redis.io/docs/latest/commands/unwatch/">Unwatch all keys</Card>
<Card title="WATCH" href="https://redis.io/docs/latest/commands/watch/">Watch keys for changes</Card>
</CardGroup>
</Accordion>

</AccordionGroup>

***

We run command integration tests from the following Redis clients after each code change and also periodically:

* **[Node-Redis](https://github.com/redis/node-redis)**
* **[Jedis](https://github.com/redis/jedis)**
* **[Lettuce](https://github.com/lettuce-io/lettuce-core)**
* **[Go-Redis](https://github.com/go-redis/redis)**
* **[Redis-py](https://github.com/redis/redis-py)**

# 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.

All features of Prod Pack and Enterprise plan for Upstash Redis are detailed below.

## How to Upgrade

You can activate Prod Pack on the database details page in the [Upstash Console](https://upstash.com/dashboard/redis). For the Enterprise plan, please create a request through the or contact [support@upstash.com](mailto:support@upstash.com).

# Prod Pack Features
These features are available on databases with Prod Pack.

### 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. Learn more about [Uptime SLA](/docs/common/help/sla).

### SOC-2 Type 2 Compliance & Report
SOC-2 Type 2 controls apply at the platform level. Prod Pack adds customer-facing compliance support, including SOC-2 report access, contractual commitments, and audit-ready features such as encryption at rest, credential protection, and advanced monitoring. Once enabled, you can request the report through the [Upstash Trust Center](https://trust.upstash.com/) or by contacting [support@upstash.com](mailto:support@upstash.com).

### Multi-Zone High Availability

With Prod Pack add-on, regions of your database are deployed with [multi-zone high availability](/docs/redis/features/replication#high-availability). If one replica or availability zone fails, another replica in a different zone continues serving traffic in the same region. This ensures that your database remains available 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.

### 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. Learn more about [Prometheus integration](/docs/redis/integrations/prometheus).

### 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. Learn more about [Datadog integration](/docs/redis/howto/datadog).

### 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.

# Enterprise Features

All Prod Pack features are included in the Enterprise plan. Additionally, Enterprise plans include:

### Custom Limits
Get a custom-tailored plan for your Upstash Redis databases to handle the growing demands of your business at any scale, such as 100K+ commands per second, unlimited bandwidth, and higher storage limits.

### SAML 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.

### Unlimited Database Count
Enterprise plans include unlimited database count, allowing you to scale your infrastructure without database count restrictions.

### 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](/docs/common/help/prosupport) for more details.

### Dedicated Resources for Isolation
Enterprise customers receive dedicated resources to ensure isolation and consistent performance for their database workloads.

### 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.

### HIPAA Compliance
A Business Associate Agreement (BAA) and HIPAA compliance enablement is available with our Enterprise plan.

# Getting Started
Source: https://upstash.com/docs/redis/overall/getstarted

Upstash Redis is a **highly available, infinitely scalable** Redis-compatible database:

* 99.99% uptime guarantee with auto-scaling ([Prod Pack](/docs/redis/overall/enterprise#prod-pack-features))
* Ultra-low latency worldwide
* Multi-region replication
* Multi-Zone High Availability ([Prod Pack](/docs/redis/overall/enterprise#prod-pack-features))
* Durable, persistent storage without sacrificing performance
* Automatic backups
* Optional SOC-2 compliance, encryption at rest and much more

***

## 1. Create an Upstash Redis Database

Log in to the [Upstash Console](https://console.upstash.com) (or [sign up](https://console.upstash.com) for a free account). From the **Redis** tab, click `+ Create Database` in the upper right corner. A dialog opens up:

<img />

**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/connect-client) section for connecting via our TypeScript or Python SDKs and other clients.

<Tip>
  You can copy the `redis-cli` command to connect to your database from the **Details** tab of your database in the Upstash Console.
</Tip>

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! 🎉

<Check>
**New: Manage Upstash Redis with your agent**

Manage Upstash Redis databases from Claude and other AI tools by using our [MCP server](/docs/agent-resources/mcp).
</Check>

## Next steps

* [Connect your client](../howto/connect-client): TypeScript, Python, Go, Java, and other Redis clients.
* [Use cases](/docs/redis/overall/usecases): caching, rate limiting, queues, pub/sub, AI workloads, and more.
* [Upstash Redis Search](/docs/redis/search/introduction): full-text search built into Upstash Redis.
* [REST API](/docs/redis/features/restapi): connect from edge and serverless runtimes where TCP is restricted.

# llms.txt
Source: https://upstash.com/docs/redis/overall/llms-txt

# Pricing & Limits
Source: https://upstash.com/docs/redis/overall/pricing

Please check our [pricing page](https://upstash.com/pricing/redis) for the most up-to-date information on pricing and limits.

## Choosing a plan

Upstash Redis has two paid plans:

* **Pay-As-You-Go (PAYG).** Billed per request. Best for variable or low-volume workloads where command volume is unpredictable, such as caching in serverless functions, edge workloads, and apps that scale to zero. To help prevent unexpected charges, it's possible to set a monthly budget on pay-as-you-go plans.

* **Fixed plans.** A flat monthly price with a cap on throughput and data size. Usually cheaper than PAYG for sustained, high-throughput workloads where command count is consistently high and predictable. Worker-heavy setups such as Sidekiq, BullMQ, Celery, and cron jobs are a common fit.

You can start on PAYG and switch to a Fixed plan later, or vice versa. See [all plans and limits](https://upstash.com/pricing) for the full breakdown.

# Pricing & Limits
Source: https://upstash.com/docs/redis/overall/pricingold

# Python SDK
Source: https://upstash.com/docs/redis/overall/pythonredis

# Rate Limit SDK
Source: https://upstash.com/docs/redis/overall/ratelimit

# Typescript SDK
Source: https://upstash.com/docs/redis/overall/redis

# Use Cases
Source: https://upstash.com/docs/redis/overall/usecases

The data store behind Upstash is [compatible](/docs/redis/overall/compatibility)
with almost all Redis® API. So you can use Upstash for the Redis®' popular use
cases such as:

* General caching
* Session caching
* Rate limiting (see [`@upstash/ratelimit`](https://github.com/upstash/ratelimit))
* Queues and background jobs (works with [Sidekiq](/docs/redis/integrations/sidekiq), [BullMQ](/docs/redis/integrations/bullmq), [Celery](/docs/redis/integrations/celery))
* Distributed locking
* Pub/Sub
* Feature flags
* Full-text search inside Redis with [Upstash Redis Search](/docs/redis/search/introduction) (auto-synced, works with JSON, Hashes, and Strings out of the box)
* Leaderboards
* Recommendations
* Usage metering (counting)
* Content filtering
* LLM response caching, chat history, and agent memory for AI applications

Upstash runs anywhere your application runs: traditional servers and containers (EC2, Render, Fly.io, Railway, Kubernetes) over native Redis TCP, serverless functions (AWS Lambda, Vercel Functions, Google Cloud Functions) over TCP or REST, and edge runtimes (Cloudflare Workers, Vercel Edge, Deno Deploy) over the REST API.

Check Salvatore's [blog](http://antirez.com/post/take-advantage-of-redis-adding-it-to-your-stack.html) post. You can find lots of similar articles about the common use cases of Redis.

## Key Value Store and Caching for Next.js Application

Next.js is increasingly becoming the preferred method for developing dynamic and fast web applications in an agile manner. It owes its popularity to its server-side rendering capabilities and API routes supported by serverless functions, including Vercel serverless and edge functions. Upstash Redis is a great fit with Next.js applications due to its serverless model and its REST-based APIs. The REST API plays a critical role in enabling access from edge functions while also addressing connection issues in serverless functions.

Check the blog post:
[Speed up your Next.js application with Redis](https://upstash.com/blog/nextjs-caching-with-redis)

## Redis for Vercel Functions

Vercel stands out as one of the most popular cloud platform for web developers, offering continuous integration, deployment, CDN and serverless functions. However, when it comes to databases, you'll need to rely on external data services to support dynamic applications.

That's where Upstash comes into play as one of the most favored data solutions within the Vercel platform. Here are some reasons that contribute to Upstash's popularity in the Vercel ecosystem:

* No connection problems thanks to
  [Upstash SDK](https://github.com/upstash/upstash-redis) built on Upstash REST
  API.
* Edge runtime does not allow TCP based connections. You can not use regular
  Redis clients. [Upstash SDK](https://github.com/upstash/upstash-redis) works
  on edge runtimes without a problem.
* Upstash has a [Vercel add on](https://vercel.com/integrations/upstash) where
  you can easily integrate Upstash to your Vercel projects.

## Storage For Lambda Functions (FaaS)

People use Lambda functions for various reasons, with one of the primary advantages being their cost-effectiveness – you only pay for what you actually use, which is great. However, when it comes to needing a storage layer, AWS recommends DynamoDB. DynamoDB does offer a serverless mode, which sounds promising until you encounter its latency when connecting and operating within Lambda Functions. Unfortunately, DynamoDB's latency may not be ideal for Lambda Functions, where every second of latency can have a significant impact on costs. At this point, AWS suggests using ElastiCache for low-latency data storage, which is also a Redis® cache as a service – a positive aspect. However, it's worth noting that ElastiCache is not serverless, and you have to pay based on what you provision, rather than what you use. To be honest, the pricing may not be the most budget-friendly option. This leaves you with two alternatives:

* DynamoDB: Serverless but high latency
* ElastiCache: Low latency but not serverless.

Until you meet the Upstash. Our sole mission is to provide a Redis® API
compatible database that you love in the serverless model. In Upstash, you pay
per the number of requests you have sent to your database. So if you are not
using the database you pay almost nothing. (Almost, because we charge for the
storage. It is a very low amount but still it is there.)

We believe that Upstash is the best storage for your Lambda Functions because:

* Serverless just like Lambda functions itself
* Designed for low latency data access
* The lovely simple Redis® API

## Detailed Tutorials

<CardGroup cols={2}>
  <Card
    title="Building Analytics with Redis"
    icon="chart-line"
    href="https://upstash.com/blog/building-analytics-with-redis"
  >
    Count and query events with counters, bitmaps, and Redis Search
  </Card>
  <Card
    title="Agent Memory with Redis Search"
    icon="brain"
    href="/redis/tutorials/agent_memory"
  >
    Short-term and long-term memory for AI agents on Upstash Redis
  </Card>
  <Card
    title="Caching in Laravel with Redis"
    icon="laravel"
    href="/redis/tutorials/laravel_caching"
  >
    Speed up your Laravel application with Upstash Redis caching
  </Card>
  <Card
    title="Cloudflare Workers with Websockets and Redis"
    icon="cloudflare"
    href="/redis/tutorials/cloudflare_websockets_redis"
  >
    Build realtime apps on Cloudflare Workers backed by Upstash Redis
  </Card>
</CardGroup>

- [AWS Lambda](https://upstash.com/docs/redis/quickstarts/aws-lambda.md)
- [Azure Functions](https://upstash.com/docs/redis/quickstarts/azure-functions.md)
- [Cloudflare Workers](https://upstash.com/docs/redis/quickstarts/cloudflareworkers.md)
- [Deno Deploy](https://upstash.com/docs/redis/quickstarts/deno-deploy.md)
- [DigitalOcean](https://upstash.com/docs/redis/quickstarts/digitalocean.md)
- [Django](https://upstash.com/docs/redis/quickstarts/django.md)
- [Elixir](https://upstash.com/docs/redis/quickstarts/elixir.md): Tutorial on Using Upstash Redis In Your Phoenix App and Deploying it on Fly.
- [FastAPI](https://upstash.com/docs/redis/quickstarts/fastapi.md)
- [Fastly](https://upstash.com/docs/redis/quickstarts/fastlycompute.md)
- [Flask](https://upstash.com/docs/redis/quickstarts/flask.md)
- [Fly.io](https://upstash.com/docs/redis/quickstarts/fly.md)
- [Google Cloud Functions](https://upstash.com/docs/redis/quickstarts/google-cloud-functions.md)
- [Ion](https://upstash.com/docs/redis/quickstarts/ion.md)
- [ioredis note](https://upstash.com/docs/redis/quickstarts/ioredisnote.md)
- [Koyeb](https://upstash.com/docs/redis/quickstarts/koyeb.md)
- [Laravel](https://upstash.com/docs/redis/quickstarts/laravel.md)
- [App Router](https://upstash.com/docs/redis/quickstarts/nextjs-app-router.md)
- [Pages Router](https://upstash.com/docs/redis/quickstarts/nextjs-pages-router.md)
- [ AWS Lambda](https://upstash.com/docs/redis/quickstarts/python-aws-lambda.md)
- [SST v2](https://upstash.com/docs/redis/quickstarts/sst-v2.md)
- [Supabase Functions](https://upstash.com/docs/redis/quickstarts/supabase.md)
- [App Router](https://upstash.com/docs/redis/quickstarts/vercel-functions-app-router.md)
- [Pages Router](https://upstash.com/docs/redis/quickstarts/vercel-functions-pages-router.md)
- [Vercel Python Runtime](https://upstash.com/docs/redis/quickstarts/vercel-python-runtime.md)
- [ECHO](https://upstash.com/docs/redis/sdks/py/commands/auth/echo.md)
- [PING](https://upstash.com/docs/redis/sdks/py/commands/auth/ping.md): Send a ping to the server and get a response if the server is alive.
- [BITCOUNT](https://upstash.com/docs/redis/sdks/py/commands/bitmap/bitcount.md): Count the number of set bits.
- [BITFIELD](https://upstash.com/docs/redis/sdks/py/commands/bitmap/bitfield.md): Sets or gets parts of a bitfield
- [BITOP](https://upstash.com/docs/redis/sdks/py/commands/bitmap/bitop.md): Perform bitwise operations between strings.
- [BITPOS](https://upstash.com/docs/redis/sdks/py/commands/bitmap/bitpos.md): Find the position of the first set or clear bit (bit with a value of 1 or 0) in a Redis string key.
- [GETBIT](https://upstash.com/docs/redis/sdks/py/commands/bitmap/getbit.md): Retrieve a single bit.
- [SETBIT](https://upstash.com/docs/redis/sdks/py/commands/bitmap/setbit.md): Set a single bit in a string.
- [CLIENT SETINFO](https://upstash.com/docs/redis/sdks/py/commands/connection/client_setinfo.md): Set client library name and version information.
- [DEL](https://upstash.com/docs/redis/sdks/py/commands/generic/del.md): Removes the specified keys. A key is ignored if it does not exist.
- [EXISTS](https://upstash.com/docs/redis/sdks/py/commands/generic/exists.md): Check if a key exists.
- [EXPIRE](https://upstash.com/docs/redis/sdks/py/commands/generic/expire.md): Sets a timeout on key. The key will automatically be deleted.
- [EXPIREAT](https://upstash.com/docs/redis/sdks/py/commands/generic/expireat.md): Sets a timeout on key. The key will automatically be deleted.
- [KEYS](https://upstash.com/docs/redis/sdks/py/commands/generic/keys.md): Returns all keys matching pattern.
- [PERSIST](https://upstash.com/docs/redis/sdks/py/commands/generic/persist.md): Remove any timeout set on the key.
- [PEXPIRE](https://upstash.com/docs/redis/sdks/py/commands/generic/pexpire.md): Sets a timeout on key. After the timeout has expired, the key will automatically be deleted.
- [PEXPIREAT](https://upstash.com/docs/redis/sdks/py/commands/generic/pexpireat.md): Sets a timeout on key. After the timeout has expired, the key will automatically be deleted.
- [PTTL](https://upstash.com/docs/redis/sdks/py/commands/generic/pttl.md): Return the expiration in milliseconds of a key.
- [RANDOMKEY](https://upstash.com/docs/redis/sdks/py/commands/generic/randomkey.md): Returns a random key from database
- [RENAME](https://upstash.com/docs/redis/sdks/py/commands/generic/rename.md): Rename a key
- [RENAMENX](https://upstash.com/docs/redis/sdks/py/commands/generic/renamenx.md): Rename a key if it does not already exist.
- [SCAN](https://upstash.com/docs/redis/sdks/py/commands/generic/scan.md): Scan the database for keys.
- [TOUCH](https://upstash.com/docs/redis/sdks/py/commands/generic/touch.md): Alters the last access time of one or more keys
- [TTL](https://upstash.com/docs/redis/sdks/py/commands/generic/ttl.md): Return the expiration in seconds of a key.
- [TYPE](https://upstash.com/docs/redis/sdks/py/commands/generic/type.md): Get the type of a key.
- [UNLINK](https://upstash.com/docs/redis/sdks/py/commands/generic/unlink.md): Removes the specified keys. A key is ignored if it does not exist.
- [HDEL](https://upstash.com/docs/redis/sdks/py/commands/hash/hdel.md): Deletes one or more hash fields.
- [HEXISTS](https://upstash.com/docs/redis/sdks/py/commands/hash/hexists.md): Checks if a field exists in a hash.
- [HEXPIRE](https://upstash.com/docs/redis/sdks/py/commands/hash/hexpire.md): Set a timeout on a hash field in seconds.
- [HEXPIREAT](https://upstash.com/docs/redis/sdks/py/commands/hash/hexpireat.md): Sets an expiration time for field(s) in a hash in seconds since the Unix epoch.
- [HEXPIRETIME](https://upstash.com/docs/redis/sdks/py/commands/hash/hexpiretime.md): Retrieves the expiration time of field(s) in a hash in seconds.
- [HGET](https://upstash.com/docs/redis/sdks/py/commands/hash/hget.md): Retrieves the value of a hash field.
- [HGETALL](https://upstash.com/docs/redis/sdks/py/commands/hash/hgetall.md): Retrieves all fields from a hash.
- [HGETDEL](https://upstash.com/docs/redis/sdks/py/commands/hash/hgetdel.md): Get and delete hash fields atomically.
- [HGETEX](https://upstash.com/docs/redis/sdks/py/commands/hash/hgetex.md): Get hash fields with expiration support.
- [HINCRBY](https://upstash.com/docs/redis/sdks/py/commands/hash/hincrby.md): Increments the value of a hash field by a given amount
- [HINCRBYFLOAT](https://upstash.com/docs/redis/sdks/py/commands/hash/hincrbyfloat.md): Increments the value of a hash field by a given float value.
- [HKEYS](https://upstash.com/docs/redis/sdks/py/commands/hash/hkeys.md): Return all field names in the hash stored at key.
- [HLEN](https://upstash.com/docs/redis/sdks/py/commands/hash/hlen.md): Returns the number of fields contained in the hash stored at key.
- [HMGET](https://upstash.com/docs/redis/sdks/py/commands/hash/hmget.md): Return the requested fields and their values.
- [HMSET](https://upstash.com/docs/redis/sdks/py/commands/hash/hmset.md): Write multiple fields to a hash.
- [HPERSIST](https://upstash.com/docs/redis/sdks/py/commands/hash/hpersist.md): Remove the expiration from one or more hash fields.
- [HPEXPIRE](https://upstash.com/docs/redis/sdks/py/commands/hash/hpexpire.md): Set a timeout on a hash field in milliseconds.
- [HPEXPIREAT](https://upstash.com/docs/redis/sdks/py/commands/hash/hpexpireat.md): Sets an expiration time for field(s) in a hash in milliseconds since the Unix epoch.
- [HPEXPIRETIME](https://upstash.com/docs/redis/sdks/py/commands/hash/hpexpiretime.md): Retrieves the expiration time of a field in a hash in milliseconds.
- [HPTTL](https://upstash.com/docs/redis/sdks/py/commands/hash/hpttl.md): Retrieves the remaining time-to-live (TTL) for field(s) in a hash in milliseconds.
- [HRANDFIELD](https://upstash.com/docs/redis/sdks/py/commands/hash/hrandfield.md): Return a random field from a hash
- [HSCAN](https://upstash.com/docs/redis/sdks/py/commands/hash/hscan.md): Scan a hash for fields.
- [HSET](https://upstash.com/docs/redis/sdks/py/commands/hash/hset.md): Write one or more fields to a hash.
- [HSETEX](https://upstash.com/docs/redis/sdks/py/commands/hash/hsetex.md): Set hash fields with expiration support.
- [HSETNX](https://upstash.com/docs/redis/sdks/py/commands/hash/hsetnx.md): Write a field to a hash but only if the field does not exist.
- [HSTRLEN](https://upstash.com/docs/redis/sdks/py/commands/hash/hstrlen.md): Returns the string length of a value in a hash.
- [HTTL](https://upstash.com/docs/redis/sdks/py/commands/hash/httl.md): Retrieves the remaining time-to-live (TTL) for field(s) in a hash in seconds.
- [HVALS](https://upstash.com/docs/redis/sdks/py/commands/hash/hvals.md): Returns all values in the hash stored at key.
- [JSON.ARRAPPEND](https://upstash.com/docs/redis/sdks/py/commands/json/arrappend.md): Append values to the array at path in the JSON document at key.
- [JSON.ARRINDEX](https://upstash.com/docs/redis/sdks/py/commands/json/arrindex.md): Search for the first occurrence of a JSON value in an array.
- [JSON.ARRINSERT](https://upstash.com/docs/redis/sdks/py/commands/json/arrinsert.md): Insert the json values into the array at path before the index (shifts to the right).
- [JSON.ARRLEN](https://upstash.com/docs/redis/sdks/py/commands/json/arrlen.md): Report the length of the JSON array at `path` in `key`.
- [JSON.ARRPOP](https://upstash.com/docs/redis/sdks/py/commands/json/arrpop.md): Remove and return an element from the index in the array. By default the last element from an array is popped.
- [JSON.ARRTRIM](https://upstash.com/docs/redis/sdks/py/commands/json/arrtrim.md): Trim an array so that it contains only the specified inclusive range of elements.
- [JSON.CLEAR](https://upstash.com/docs/redis/sdks/py/commands/json/clear.md): Clear container values (arrays/objects) and set numeric values to 0.
- [JSON.DEL](https://upstash.com/docs/redis/sdks/py/commands/json/del.md): Delete a key from a JSON document.
- [JSON.FORGET](https://upstash.com/docs/redis/sdks/py/commands/json/forget.md): Delete a key from a JSON document.
- [JSON.GET](https://upstash.com/docs/redis/sdks/py/commands/json/get.md): Get a single value from a JSON document.
- [JSON.MERGE](https://upstash.com/docs/redis/sdks/py/commands/json/merge.md): Merges the JSON value at path in key with the provided value.
- [JSON.MGET](https://upstash.com/docs/redis/sdks/py/commands/json/mget.md): Get the same path from multiple JSON documents.
- [JSON.MSET](https://upstash.com/docs/redis/sdks/py/commands/json/mset.md): Sets multiple JSON values at multiple paths in multiple keys.
- [JSON.NUMINCRBY](https://upstash.com/docs/redis/sdks/py/commands/json/numincrby.md): Increment the number value stored at `path` by number.
- [JSON.NUMMULTBY](https://upstash.com/docs/redis/sdks/py/commands/json/nummultby.md): Multiply the number value stored at `path` by number.
- [JSON.OBJKEYS](https://upstash.com/docs/redis/sdks/py/commands/json/objkeys.md): Return the keys in the object that`s referenced by path.
- [JSON.OBJLEN](https://upstash.com/docs/redis/sdks/py/commands/json/objlen.md): Report the number of keys in the JSON object at `path` in `key`.
- [JSON.RESP](https://upstash.com/docs/redis/sdks/py/commands/json/resp.md): Return the value at the path in Redis serialization protocol format.
- [JSON.SET](https://upstash.com/docs/redis/sdks/py/commands/json/set.md): Set the JSON value at path in key.
- [JSON.STRAPPEND](https://upstash.com/docs/redis/sdks/py/commands/json/strappend.md): Append the json-string values to the string at path.
- [JSON.STRLEN](https://upstash.com/docs/redis/sdks/py/commands/json/strlen.md): Report the length of the JSON String at path in key
- [JSON.TOGGLE](https://upstash.com/docs/redis/sdks/py/commands/json/toggle.md): Toggle a boolean value stored at `path`.
- [JSON.TYPE](https://upstash.com/docs/redis/sdks/py/commands/json/type.md): Report the type of JSON value at `path`.
- [LINDEX](https://upstash.com/docs/redis/sdks/py/commands/list/lindex.md): Returns the element at index index in the list stored at key.
- [LINSERT](https://upstash.com/docs/redis/sdks/py/commands/list/linsert.md): Insert an element before or after another element in a list
- [LLEN](https://upstash.com/docs/redis/sdks/py/commands/list/llen.md): Returns the length of the list stored at key.
- [LMOVE](https://upstash.com/docs/redis/sdks/py/commands/list/lmove.md): Move an element from one list to another.
- [LPOP](https://upstash.com/docs/redis/sdks/py/commands/list/lpop.md): Remove and return the first element(s) of a list
- [LPOS](https://upstash.com/docs/redis/sdks/py/commands/list/lpos.md): Returns the index of matching elements inside a list.
- [LPUSH](https://upstash.com/docs/redis/sdks/py/commands/list/lpush.md): Push an element at the head of the list.
- [LPUSHX](https://upstash.com/docs/redis/sdks/py/commands/list/lpushx.md): Push an element at the head of the list only if the list exists.
- [LRANGE](https://upstash.com/docs/redis/sdks/py/commands/list/lrange.md): Returns the specified elements of the list stored at key.
- [LREM](https://upstash.com/docs/redis/sdks/py/commands/list/lrem.md): Remove the first `count` occurrences of an element from a list.
- [LSET](https://upstash.com/docs/redis/sdks/py/commands/list/lset.md): Set a value at a specific index.
- [LTRIM](https://upstash.com/docs/redis/sdks/py/commands/list/ltrim.md): Trim a list to the specified range
- [RPOP](https://upstash.com/docs/redis/sdks/py/commands/list/rpop.md): Remove and return the last element(s) of a list
- [RPUSH](https://upstash.com/docs/redis/sdks/py/commands/list/rpush.md): Push an element at the end of the list.
- [RPUSHX](https://upstash.com/docs/redis/sdks/py/commands/list/rpushx.md): Push an element at the end of the list only if the list exists.
- [Overview](https://upstash.com/docs/redis/sdks/py/commands/overview.md): Available Commands in upstash-redis
- [PUBLISH](https://upstash.com/docs/redis/sdks/py/commands/pubsub/publish.md): Publish a message to a channel
- [EVAL](https://upstash.com/docs/redis/sdks/py/commands/scripts/eval.md): Evaluate a Lua script server side.
- [EVAL_RO](https://upstash.com/docs/redis/sdks/py/commands/scripts/eval_ro.md): Evaluate a read-only Lua script server side.
- [EVALSHA](https://upstash.com/docs/redis/sdks/py/commands/scripts/evalsha.md): Evaluate a cached Lua script server side.
- [EVALSHA_RO](https://upstash.com/docs/redis/sdks/py/commands/scripts/evalsha_ro.md): Evaluate a cached read-only Lua script server side.
- [SCRIPT EXISTS](https://upstash.com/docs/redis/sdks/py/commands/scripts/script_exists.md): Check if scripts exist in the script cache.
- [SCRIPT FLUSH](https://upstash.com/docs/redis/sdks/py/commands/scripts/script_flush.md): Removes all scripts from the script cache.
- [SCRIPT LOAD](https://upstash.com/docs/redis/sdks/py/commands/scripts/script_load.md): Load the specified Lua script into the script cache.
- [DBSIZE](https://upstash.com/docs/redis/sdks/py/commands/server/dbsize.md): Count the number of keys in the database.
- [FLUSHALL](https://upstash.com/docs/redis/sdks/py/commands/server/flushall.md)
- [FLUSHDB](https://upstash.com/docs/redis/sdks/py/commands/server/flushdb.md)
- [SADD](https://upstash.com/docs/redis/sdks/py/commands/set/sadd.md): Adds one or more members to a set.
- [SCARD](https://upstash.com/docs/redis/sdks/py/commands/set/scard.md): Return how many members are in a set
- [SDIFF](https://upstash.com/docs/redis/sdks/py/commands/set/sdiff.md): Return the difference between sets
- [SDIFFSTORE](https://upstash.com/docs/redis/sdks/py/commands/set/sdiffstore.md): Write the difference between sets to a new set
- [SINTER](https://upstash.com/docs/redis/sdks/py/commands/set/sinter.md): Return the intersection between sets
- [SINTER](https://upstash.com/docs/redis/sdks/py/commands/set/sinterstore.md): Return the intersection between sets and store the resulting set in a key
- [SISMEMBER](https://upstash.com/docs/redis/sdks/py/commands/set/sismember.md): Check if a member exists in a set
- [SMEMBERS](https://upstash.com/docs/redis/sdks/py/commands/set/smembers.md): Return all the members of a set
- [SMISMEMBER](https://upstash.com/docs/redis/sdks/py/commands/set/smismember.md): Check if multiple members exist in a set
- [SMOVE](https://upstash.com/docs/redis/sdks/py/commands/set/smove.md): Move a member from one set to another
- [SPOP](https://upstash.com/docs/redis/sdks/py/commands/set/spop.md): Removes and returns one or more random members from a set.
- [SRANDMEMBER](https://upstash.com/docs/redis/sdks/py/commands/set/srandmember.md): Returns one or more random members from a set.
- [SREM](https://upstash.com/docs/redis/sdks/py/commands/set/srem.md): Remove one or more members from a set
- [SSCAN](https://upstash.com/docs/redis/sdks/py/commands/set/sscan.md): Scan a set
- [SUNION](https://upstash.com/docs/redis/sdks/py/commands/set/sunion.md): Return the union between sets
- [SUNIONSTORE](https://upstash.com/docs/redis/sdks/py/commands/set/sunionstore.md): Return the union between sets and store the resulting set in a key
- [XACK](https://upstash.com/docs/redis/sdks/py/commands/stream/xack.md): Removes one or multiple messages from the pending entries list of a stream consumer group.
- [XACKDEL](https://upstash.com/docs/redis/sdks/py/commands/stream/xackdel.md): Acknowledge and delete stream entries atomically.
- [XADD](https://upstash.com/docs/redis/sdks/py/commands/stream/xadd.md): Appends one or more new entries to a stream.
- [XAUTOCLAIM](https://upstash.com/docs/redis/sdks/py/commands/stream/xautoclaim.md): Changes the ownership of pending messages from one consumer to another in a stream consumer group automatically.
- [XCLAIM](https://upstash.com/docs/redis/sdks/py/commands/stream/xclaim.md): Changes the ownership of pending messages from one consumer to another in a stream consumer group.
- [XDEL](https://upstash.com/docs/redis/sdks/py/commands/stream/xdel.md): Removes the specified entries from a stream, and returns the number of entries deleted.
- [XDELEX](https://upstash.com/docs/redis/sdks/py/commands/stream/xdelex.md): Extended delete for streams with reference control.
- [XGROUP CREATE](https://upstash.com/docs/redis/sdks/py/commands/stream/xgroup_create.md): Create a new consumer group for a Redis stream.
- [XGROUP CREATECONSUMER](https://upstash.com/docs/redis/sdks/py/commands/stream/xgroup_createconsumer.md): Create a new consumer in an existing consumer group.
- [XGROUP DELCONSUMER](https://upstash.com/docs/redis/sdks/py/commands/stream/xgroup_delconsumer.md): Delete a consumer from a consumer group.
- [XGROUP DESTROY](https://upstash.com/docs/redis/sdks/py/commands/stream/xgroup_destroy.md): Delete an entire consumer group.
- [XGROUP SETID](https://upstash.com/docs/redis/sdks/py/commands/stream/xgroup_setid.md): Set the last delivered ID for a consumer group.
- [XINFO CONSUMERS](https://upstash.com/docs/redis/sdks/py/commands/stream/xinfo_consumers.md): List all consumers in a consumer group.
- [XINFO GROUPS](https://upstash.com/docs/redis/sdks/py/commands/stream/xinfo_groups.md): List all consumer groups for a stream.
- [XLEN](https://upstash.com/docs/redis/sdks/py/commands/stream/xlen.md): Returns the number of entries inside a stream.
- [XPENDING](https://upstash.com/docs/redis/sdks/py/commands/stream/xpending.md): Returns information about pending messages in a stream consumer group.
- [XRANGE](https://upstash.com/docs/redis/sdks/py/commands/stream/xrange.md): Returns stream entries matching a given range of IDs.
- [XREAD](https://upstash.com/docs/redis/sdks/py/commands/stream/xread.md): Reads data from one or multiple streams, starting from the specified IDs.
- [XREADGROUP](https://upstash.com/docs/redis/sdks/py/commands/stream/xreadgroup.md): Reads data from a stream as part of a consumer group.
- [XREVRANGE](https://upstash.com/docs/redis/sdks/py/commands/stream/xrevrange.md): Returns stream entries matching a given range of IDs in reverse order.
- [XTRIM](https://upstash.com/docs/redis/sdks/py/commands/stream/xtrim.md): Trims the stream by removing entries to keep it at a reasonable size.
- [APPEND](https://upstash.com/docs/redis/sdks/py/commands/string/append.md): Append a value to a string stored at key.
- [DECR](https://upstash.com/docs/redis/sdks/py/commands/string/decr.md): Decrement the integer value of a key by one
- [DECRBY](https://upstash.com/docs/redis/sdks/py/commands/string/decrby.md): Decrement the integer value of a key by a given number.
- [GET](https://upstash.com/docs/redis/sdks/py/commands/string/get.md): Return the value of the specified key or `None` if the key doesn't exist.
- [GETDEL](https://upstash.com/docs/redis/sdks/py/commands/string/getdel.md): Return the value of the specified key and delete the key.
- [GETRANGE](https://upstash.com/docs/redis/sdks/py/commands/string/getrange.md): Return a substring of value at the specified key.
- [GETSET](https://upstash.com/docs/redis/sdks/py/commands/string/getset.md): Return the value of the specified key and replace it with a new value.
- [INCR](https://upstash.com/docs/redis/sdks/py/commands/string/incr.md): Increment the integer value of a key by one
- [INCRBY](https://upstash.com/docs/redis/sdks/py/commands/string/incrby.md): Increment the integer value of a key by a given number.
- [INCRBYFLOAT](https://upstash.com/docs/redis/sdks/py/commands/string/incrbyfloat.md): Increment the float value of a key by a given number.
- [MGET](https://upstash.com/docs/redis/sdks/py/commands/string/mget.md): Load multiple keys from Redis in one go.
- [MSET](https://upstash.com/docs/redis/sdks/py/commands/string/mset.md): Set multiple keys in one go.
- [MSETNX](https://upstash.com/docs/redis/sdks/py/commands/string/msetnx.md): Set multiple keys in one go unless they exist already.
- [SET](https://upstash.com/docs/redis/sdks/py/commands/string/set.md): Set a key to hold a string value.
- [SETRANGE](https://upstash.com/docs/redis/sdks/py/commands/string/setrange.md): Writes the value of key at offset.
- [STRLEN](https://upstash.com/docs/redis/sdks/py/commands/string/strlen.md): Return the length of a string stored at a key.
- [ZADD](https://upstash.com/docs/redis/sdks/py/commands/zset/zadd.md): Add a member to a sorted set, or update its score if it already exists.
- [ZCARD](https://upstash.com/docs/redis/sdks/py/commands/zset/zcard.md): Returns the number of elements in the sorted set stored at key.
- [ZCOUNT](https://upstash.com/docs/redis/sdks/py/commands/zset/zcount.md): Returns the number of elements in the sorted set stored at key filterd by score.
- [ZDIFF](https://upstash.com/docs/redis/sdks/py/commands/zset/zdiff.md): Returns the difference between sets.
- [ZDIFFSTORE](https://upstash.com/docs/redis/sdks/py/commands/zset/zdiffstore.md): Writes the difference between sets to a new key.
- [ZINCRBY](https://upstash.com/docs/redis/sdks/py/commands/zset/zincrby.md): Increment the score of a member.
- [ZINTER](https://upstash.com/docs/redis/sdks/py/commands/zset/zinter.md): Returns the intersection between sets.
- [ZINTERSTORE](https://upstash.com/docs/redis/sdks/py/commands/zset/zinterstore.md): Calculates the intersection of sets and stores the result in a key
- [ZLEXCOUNT](https://upstash.com/docs/redis/sdks/py/commands/zset/zlexcount.md): Returns the number of elements in the sorted set stored at key filterd by lex.
- [ZMSCORE](https://upstash.com/docs/redis/sdks/py/commands/zset/zmscore.md): Returns the scores of multiple members.
- [ZPOPMAX](https://upstash.com/docs/redis/sdks/py/commands/zset/zpopmax.md): Removes and returns up to count members with the highest scores in the sorted set stored at key.
- [ZPOPMIN](https://upstash.com/docs/redis/sdks/py/commands/zset/zpopmin.md): Removes and returns up to count members with the lowest scores in the sorted set stored at key.
- [ZRANDMEMBER](https://upstash.com/docs/redis/sdks/py/commands/zset/zrandmember.md): Returns one or more random members from a sorted set, optionally with their scores.
- [ZRANGE](https://upstash.com/docs/redis/sdks/py/commands/zset/zrange.md): Returns the specified range of elements in the sorted set stored at key.
- [ZRANK](https://upstash.com/docs/redis/sdks/py/commands/zset/zrank.md): Returns the rank of a member
- [ZREM](https://upstash.com/docs/redis/sdks/py/commands/zset/zrem.md): Remove one or more members from a sorted set
- [ZREMRANGEBYLEX](https://upstash.com/docs/redis/sdks/py/commands/zset/zremrangebylex.md): Remove all members in a sorted set between the given lexicographical range.
- [ZREMRANGEBYRANK](https://upstash.com/docs/redis/sdks/py/commands/zset/zremrangebyrank.md): Remove all members in a sorted set between the given ranks.
- [ZREMRANGEBYSCORE](https://upstash.com/docs/redis/sdks/py/commands/zset/zremrangebyscore.md): Remove all members in a sorted set between the given scores.
- [ZREVRANK](https://upstash.com/docs/redis/sdks/py/commands/zset/zrevrank.md): Returns the rank of a member in a sorted set, with scores ordered from high to low.
- [ZSCAN](https://upstash.com/docs/redis/sdks/py/commands/zset/zscan.md): Scan a sorted set
- [ZSCORE](https://upstash.com/docs/redis/sdks/py/commands/zset/zscore.md): Returns the scores of a member.
- [ZINTER](https://upstash.com/docs/redis/sdks/py/commands/zset/zunion.md): Returns the intersection between sets.
- [ZUNIONSTORE](https://upstash.com/docs/redis/sdks/py/commands/zset/zunionstore.md): Writes the union between sets to a new key.

# 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']
```

# Telemetry

This library sends anonymous telemetry data to help us improve your experience.
We collect the following:

* SDK version
* Platform (Vercel, AWS)
* Python Runtime version

You can opt out by passing `allow_telemetry=False` when initializing the Redis client:

```py
redis = Redis(
  # ...,
  allow_telemetry=False,
)
```

# 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.

<Tip>
  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.
</Tip>

### 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),
)
```

<Tip>
  `reset` field in the [`limit`](/docs/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.
</Tip>

## 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

### Pros

* Very cheap in terms of data size and computation
* Newer requests are not starved due to a high burst in the past
* Supports [dynamic limits](/docs/redis/sdks/ratelimit-ts/features#dynamic-limits)

### 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.

<Tabs>
  <Tab title="Regional">
    ```ts
    const ratelimit = new Ratelimit({
      redis: Redis.fromEnv(),
      limiter: Ratelimit.fixedWindow(10, "10 s"),
    });
    ```
  </Tab>
  <Tab title="Multi Regional">
    ```ts
    const ratelimit = new MultiRegionRatelimit({
      redis: [
        new Redis({
          /* auth */
        }),
        new Redis({
          /* auth */
        })
      ],
      limiter: MultiRegionRatelimit.fixedWindow(10, "10 s"),
    });
    ```
  </Tab>
</Tabs>

## Sliding Window

```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.
* Supports [dynamic limits](/docs/redis/sdks/ratelimit-ts/features#dynamic-limits)

### 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.

<Tabs>
  <Tab title="Regional">
    ```ts
    const ratelimit = new Ratelimit({
      redis: Redis.fromEnv(),
      limiter: Ratelimit.slidingWindow(10, "10 s"),
    });
    ```
  </Tab>
  <Tab title="Multi Regional">
    **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](/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"),
    });
    ```

</Tab>
</Tabs>

<Tip>
  `reset` field in the [`limit`](/docs/redis/sdks/ratelimit-ts/methods#limit) and [`getRemaining`](/docs/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.
</Tip>

## 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`
* Supports [dynamic limits](/docs/redis/sdks/ratelimit-ts/features#dynamic-limits)

### 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.

<Tabs>
  <Tab title="Regional">
    ```ts
    const ratelimit = new Ratelimit({
      redis: Redis.fromEnv(),
      limiter: Ratelimit.tokenBucket(5, "10 s", 10),
      analytics: true,
    });
    ```
  </Tab>

<Tab title="Multi Regional">
    _Not yet supported for `MultiRegionRatelimit`_
  </Tab>
</Tabs>

# 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](/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](/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](/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.

# Dynamic Limits

When [dynamic limits](/docs/redis/sdks/ratelimit-ts/features#dynamic-limits) are enabled, each `limit` and `getRemaining` call will execute one additional command.

Both `setDynamicLimit` and `getDynamicLimit` execute 1 command each.

# 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<string, number>` 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`](/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](/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](/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](/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](/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:

![navigate.png]()

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.

![dashboard.png]()

**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).

## Dynamic Limits

Dynamic limits allow you to change rate limits at runtime without recreating the rate limiter instance. This is useful when you need to adjust limits based on user tiers, system load, or other dynamic factors.

To enable dynamic limits, set the `dynamicLimits` option to `true` when creating the rate limiter:

```ts
const ratelimit = new Ratelimit({
  redis: Redis.fromEnv(),
  limiter: Ratelimit.slidingWindow(10, "10s"),
  dynamicLimits: true, // Enable dynamic limits
});

// Set a global dynamic limit
await ratelimit.setDynamicLimit({ limit: 5 });

// All subsequent limit checks use the new limit
const { success } = await ratelimit.limit("user_123");

// Get current dynamic limit
const currentLimit = await ratelimit.getDynamicLimit(); // returns 5

// Remove dynamic limit (falls back to default)
await ratelimit.setDynamicLimit({ limit: false });
```

Dynamic limits work with the following single region algorithms: `fixedWindow`, `slidingWindow`, `tokenBucket`, Multi region algrorithms aren't supported.

# 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](/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`:

<Tabs>
  <Tab title="npm">
    ```bash
    npm install @upstash/ratelimit
    ```
  </Tab>
  <Tab title="deno">
    ```ts
    import { Ratelimit } from "https://cdn.skypack.dev/@upstash/ratelimit@latest";
    ```
  </Tab>
</Tabs>

### 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",
});

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](/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:

<Tabs>
  <Tab title="Vercel">
    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.
  </Tab>
  <Tab title="Cloudflare Worker (Wrangler)">
    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
    ```
  </Tab>
  <Tab title="Local Nextjs Project">
    Go to the `.env.local` file and add the environment variables:
    ```
    UPSTASH_REDIS_REST_URL=****
    UPSTASH_REDIS_REST_TOKEN=****
    ```
  </Tab>
</Tabs>

## 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 background 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);
```

## 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](/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](/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](/docs/redis/sdks/ratelimit-ts/methods).

## Features

To configure the your Ratelimit according to your needs, you can make use of several features:

<CardGroup cols={2}>
  <Card
    title="Caching"
    icon="shield-halved"
    href="/redis/sdks/ratelimit-ts/features#caching"
  >
    Handle blocked requests without having to call your Redis Database
  </Card>
  <Card
    title="Timeout"
    icon="stopwatch"
    href="/redis/sdks/ratelimit-ts/features#timeout"
  >
    If the Redis call of the ratelimit is not resolved in some timeframe, allow
    the request by default
  </Card>
  <Card
    title="Analytics & Dashboard"
    icon="magnifying-glass-chart"
    href="/redis/sdks/ratelimit-ts/features#analytics-and-dashboard"
  >
    Collect information on which identifiers made how many requests and how many
    were blocked
  </Card>
  <Card
    title="Traffic Protection"
    icon="lock"
    href="/redis/sdks/ratelimit-ts/traffic-protection"
  >
    Create a deny list to block requests based on user agents, countries, IP
    addresses an more
  </Card>
  <Card
    title="Custom Rates"
    icon="chart-simple"
    href="/redis/sdks/ratelimit-ts/features#custom-rates"
  >
    Consume different amounts of tokens in different requests (example: limiting
    based on request/response size)
  </Card>
  <Card
    title="Multi Region"
    icon="globe"
    href="/redis/sdks/ratelimit-ts/features#multi-region"
  >
    Utilize several Redis databases in different regions to serve users faster
  </Card>
  <Card
    title="Multiple Limits"
    icon="gears"
    href="/redis/sdks/ratelimit-ts/features#using-multiple-limits"
  >
    Use different limits for different kinds of requests (example: paid and free
    users)
  </Card>
  <Card
    title="Dynamic Limits"
    icon="sliders"
    href="/redis/sdks/ratelimit-ts/features#dynamic-limits"
  >
    Change rate limits at runtime without recreating the rate limiter instance
  </Card>
</CardGroup>

For more information about the features, see the [Features page](/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

<ParamField path="enabled" type="boolean" default="true">
  Enable or disable the plugin.
</ParamField>

## Database Configurations

## Strategy

The plugin uses a strategy array to define the rate limits per route. Each strategy object has the following properties:

<ParamField path="debug" type="string">
  Enable debug mode for the route. When enabled, the plugin logs the remaining
  limits and the block status for each request. <br />
</ParamField>

<ParamField path="limiter" type="object" required>
  The limiter configuration for the route. The limiter object has the following
  properties:

## Examples

</CodeGroup>

# Upstash Ratelimit Strapi Integration
Source: https://upstash.com/docs/redis/sdks/ratelimit-ts/integrations/strapi/getting-started

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
```

</CodeGroup>

### Create database

Create a new redis database on [Upstash Console](https://console.upstash.com/). See [related docs](/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="<YOUR_TOKEN>"
UPSTASH_REDIS_REST_URL="<YOUR_URL>"
```

### Configure the plugin

You can use

</CodeGroup>

# 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](/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<RatelimitResponse>
```

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<unknown>;

/**
   * 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<RatelimitResponse>
```

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!";
```

<Warning>
  In **Cloudflare**, `blockUntilReady` will not work as intended due to
  `Date.now()` not behaving the same as in Node environments.
  <br />
  <br />
  **For more information, check**: <br />
  https://developers.cloudflare.com/workers/runtime-apis/web-standards
</Warning>

## `resetUsedTokens`

This method resets the state of the algorithm with respect to some identifier:

```ts
ratelimit.resetUsedTokens(identifier: string): Promise<void>
```

## `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.

## `setDynamicLimit`

This method sets or removes a [global dynamic rate limit](/docs/redis/sdks/ratelimit-ts/features#dynamic-limits). Dynamic limits override the default limiter settings for all subsequent rate limit checks.

```ts
ratelimit.setDynamicLimit(options: {
  limit: number | false;
}): Promise<void>
```

**Parameters:**
* `limit`: The new limit value (number), or `false` to remove the dynamic limit and fall back to the default

**Example:**

```ts
const ratelimit = new Ratelimit({
  redis: Redis.fromEnv(),
  limiter: Ratelimit.slidingWindow(10, "10s"),
  dynamicLimits: true,
});

// Set a new dynamic limit
await ratelimit.setDynamicLimit({ limit: 5 });

// Remove dynamic limit (falls back to default of 10)
await ratelimit.setDynamicLimit({ limit: false });
```

## `getDynamicLimit`

This method retrieves the current [dynamic limit](/docs/redis/sdks/ratelimit-ts/features#dynamic-limits) if one is set.

```ts
ratelimit.getDynamicLimit(): Promise<{ dynamicLimit: number | null }>
```

**Returns:** The current dynamic limit value, or `null` if no dynamic limit is set

**Example:**

```ts
const ratelimit = new Ratelimit({
  redis: Redis.fromEnv(),
  limiter: Ratelimit.slidingWindow(10, "10s"),
  dynamicLimits: true,
});

await ratelimit.setDynamicLimit({ limit: 5 });
const { dynamicLimit } = await ratelimit.getDynamicLimit(); // returns 5
```

# Overview
Source: https://upstash.com/docs/redis/sdks/ratelimit-ts/overview

# Upstash Rate Limit

[![npm (scoped)]()](https://www.npmjs.com/package/@upstash/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](/docs/redis/sdks/ratelimit-ts/gettingstarted)
* [Costs](/docs/redis/sdks/ratelimit-ts/costs)

## Features

<CardGroup cols={2}>
  <Card
    title="Caching"
    icon="shield-halved"
    href="/redis/sdks/ratelimit-ts/features#caching"
  >
    Handle blocked requests without having to call your Redis Database
  </Card>
  <Card
    title="Timeout"
    icon="stopwatch"
    href="/redis/sdks/ratelimit-ts/features#timeout"
  >
    If the Redis call of the ratelimit is not resolved in some timeframe, allow
    the request by default
  </Card>
  <Card
    title="Analytics & Dashboard"
    icon="magnifying-glass-chart"
    href="/redis/sdks/ratelimit-ts/features#analytics-and-dashboard"
  >
    Collect information on which identifiers made how many requests and how many
    were blocked
  </Card>
  <Card
    title="Traffic Protection"
    icon="lock"
    href="/redis/sdks/ratelimit-ts/traffic-protection"
  >
    Create a deny list to block requests based on user agents, countries, IP
    addresses and more
  </Card>
  <Card
    title="Custom Rates"
    icon="chart-simple"
    href="/redis/sdks/ratelimit-ts/features#custom-rates"
  >
    Consume different amounts of tokens in different requests (example: limiting
    based on request/response size)
  </Card>
  <Card
    title="Multi Region"
    icon="globe"
    href="/redis/sdks/ratelimit-ts/features#multi-region"
  >
    Utilize several Redis databases in different regions to serve users faster
  </Card>
  <Card
    title="Multiple Limits"
    icon="gears"
    href="/redis/sdks/ratelimit-ts/features#using-multiple-limits"
  >
    Use different limits for different kinds of requests (example: paid and free
    users)
  </Card>
  <Card
    title="Dynamic Limits"
    icon="sliders"
    href="/redis/sdks/ratelimit-ts/features#dynamic-limits"
  >
    Change rate limits at runtime without recreating the rate limiter instance
  </Card>
</CardGroup>

For more information about the features, see the [Features tab](/docs/redis/sdks/ratelimit-ts/features).

## Examples

<CardGroup cols={2}>
  <Card
    title="Nextjs"
    href="https://github.com/upstash/ratelimit/tree/main/examples/nextjs"
  >
    Rate limit an API in a Nextjs project
  </Card>
  <Card
    title="Nextjs with Middleware"
    href="https://github.com/upstash/ratelimit/tree/main/examples/nextjs-middleware"
  >
    Rate limit an API with a Middleware in a Nextjs project
  </Card>
  <Card
    title="Vercel Edge"
    href="https://github.com/upstash/ratelimit/tree/main/examples/vercel-edge"
  >
    Rate limit an Vercel Edge Function
  </Card>
  <Card
    title="Enabling Protection"
    href="https://github.com/upstash/ratelimit/tree/main/examples/enable-protection"
  >
    Use Deny Lists to Protect Your Website
  </Card>
  <Card
    title="Cloudflare Pages"
    href="https://github.com/upstash/ratelimit/tree/main/examples/cloudflare-pages"
  >
    Rate limit access to your Cloudflare Pages app
  </Card>
  <Card
    title="Cloudflare Workers"
    href="https://github.com/upstash/ratelimit/tree/main/examples/cloudflare-workers"
  >
    Rate limit access to your Cloudflare Workers
  </Card>
  <Card
    title="Remix"
    href="https://github.com/upstash/ratelimit/tree/main/examples/remix"
  >
    Rate limit access to a Remix App
  </Card>
  <Card
    title="Rate limit using Vercel KV"
    href="https://github.com/upstash/ratelimit/tree/main/examples/with-vercel-kv"
  >
    Rate limit a Nexjs app using Vercel KV
  </Card>
  <Card
    title="Deno App"
    href="https://github.com/upstash/ratelimit/tree/main/examples/deno"
  >
    Rate limit your deno app
  </Card>
  <Card
    title="Rate limit your Chatbot"
    href="https://upstash.com/blog/degree-guru#rate-limiting"
  >
    Limiting requests to a Chatbot endpoint which streams LLM outputs
  </Card>
</CardGroup>

# 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](/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](/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](/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.

![denylist.png]()

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](/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.

<Tip>This functionality is enabled by default.</Tip>

## Request Timeout

You can configure the SDK so that it will throw an error if the request takes longer than a specified time.

You can achieve this using the signal parameter like this:

```ts
const redis = new Redis({
  url: "<UPSTASH_REDIS_REST_URL>",
  token: "<UPSTASH_REDIS_REST_TOKEN>",
  // set a timeout of 1 second
  signal: () => AbortSignal.timeout(1000),
});

try {
  await redis.get( ... )
} catch (error) {
  if (error.name === "TimeoutError") {
    console.error("Request timed out");
  } else {
    console.error("An error occurred:", error);
  }
}
```

## Telemetry

This library sends anonymous telemetry data to help us improve your experience.
We collect the following:

* SDK version
* Platform (Deno, Cloudflare, Vercel)
* Runtime version (node@18.x)

You can opt out by setting the `UPSTASH_DISABLE_TELEMETRY` environment variable
to any truthy value.

```sh
UPSTASH_DISABLE_TELEMETRY=1
```

Alternatively, you can pass `enableTelemetry: false` when initializing the Redis client:

```ts
const redis = new Redis({
  // ...,
  enableTelemetry: false,
});
```

- [ECHO](https://upstash.com/docs/redis/sdks/ts/commands/auth/echo.md)
- [PING](https://upstash.com/docs/redis/sdks/ts/commands/auth/ping.md): Send a ping to the server and get a response if the server is alive.
- [BITCOUNT](https://upstash.com/docs/redis/sdks/ts/commands/bitmap/bitcount.md): Count the number of set bits.
- [BITOP](https://upstash.com/docs/redis/sdks/ts/commands/bitmap/bitop.md): Perform bitwise operations between strings.
- [BITPOS](https://upstash.com/docs/redis/sdks/ts/commands/bitmap/bitpos.md): Find the position of the first set or clear bit (bit with a value of 1 or 0) in a Redis string key.
- [GETBIT](https://upstash.com/docs/redis/sdks/ts/commands/bitmap/getbit.md): Retrieve a single bit.
- [SETBIT](https://upstash.com/docs/redis/sdks/ts/commands/bitmap/setbit.md): Set a single bit in a string.
- [CLIENT SETINFO](https://upstash.com/docs/redis/sdks/ts/commands/connection/client_setinfo.md): Set client library name and version information.
- [FCALL](https://upstash.com/docs/redis/sdks/ts/commands/functions/call.md): Invoke a function.
- [FCALL_RO](https://upstash.com/docs/redis/sdks/ts/commands/functions/call_ro.md): Invoke a read-only function
- [FUNCTION DELETE](https://upstash.com/docs/redis/sdks/ts/commands/functions/delete.md): Delete a library and all its functions.
- [FUNCTION FLUSH](https://upstash.com/docs/redis/sdks/ts/commands/functions/flush.md): Delete all the libraries and functions.
- [FUNCTION LIST](https://upstash.com/docs/redis/sdks/ts/commands/functions/list.md): List details about the registered libraries and functions.
- [FUNCTION LOAD](https://upstash.com/docs/redis/sdks/ts/commands/functions/load.md): Load a library to Redis.
- [FUNCTION STATS](https://upstash.com/docs/redis/sdks/ts/commands/functions/stats.md): Return information about the function running engine.
- [DEL](https://upstash.com/docs/redis/sdks/ts/commands/generic/del.md): Removes the specified keys. A key is ignored if it does not exist.
- [EXISTS](https://upstash.com/docs/redis/sdks/ts/commands/generic/exists.md): Check if a key exists.
- [EXPIRE](https://upstash.com/docs/redis/sdks/ts/commands/generic/expire.md): Sets a timeout on key. The key will automatically be deleted.
- [EXPIREAT](https://upstash.com/docs/redis/sdks/ts/commands/generic/expireat.md): Sets a timeout on key. The key will automatically be deleted.
- [KEYS](https://upstash.com/docs/redis/sdks/ts/commands/generic/keys.md): Returns all keys matching pattern.
- [PERSIST](https://upstash.com/docs/redis/sdks/ts/commands/generic/persist.md): Remove any timeout set on the key.
- [PEXPIRE](https://upstash.com/docs/redis/sdks/ts/commands/generic/pexpire.md): Sets a timeout on key. After the timeout has expired, the key will automatically be deleted.
- [PEXPIREAT](https://upstash.com/docs/redis/sdks/ts/commands/generic/pexpireat.md): Sets a timeout on key. After the timeout has expired, the key will automatically be deleted.
- [PTTL](https://upstash.com/docs/redis/sdks/ts/commands/generic/pttl.md): Return the expiration in milliseconds of a key.
- [RANDOMKEY](https://upstash.com/docs/redis/sdks/ts/commands/generic/randomkey.md): Returns a random key from database
- [RENAME](https://upstash.com/docs/redis/sdks/ts/commands/generic/rename.md): Rename a key
- [RENAMENX](https://upstash.com/docs/redis/sdks/ts/commands/generic/renamenx.md): Rename a key if it does not already exist.
- [SCAN](https://upstash.com/docs/redis/sdks/ts/commands/generic/scan.md): Scan the database for keys.
- [TOUCH](https://upstash.com/docs/redis/sdks/ts/commands/generic/touch.md): Alters the last access time of one or more keys
- [TTL](https://upstash.com/docs/redis/sdks/ts/commands/generic/ttl.md): Return the expiration in seconds of a key.
- [TYPE](https://upstash.com/docs/redis/sdks/ts/commands/generic/type.md): Get the type of a key.
- [UNLINK](https://upstash.com/docs/redis/sdks/ts/commands/generic/unlink.md): Removes the specified keys. A key is ignored if it does not exist.
- [HDEL](https://upstash.com/docs/redis/sdks/ts/commands/hash/hdel.md): Deletes one or more hash fields.
- [HEXISTS](https://upstash.com/docs/redis/sdks/ts/commands/hash/hexists.md): Checks if a field exists in a hash.
- [HEXPIRE](https://upstash.com/docs/redis/sdks/ts/commands/hash/hexpire.md): Sets an expiration time for one or more fields in a hash.
- [HEXPIREAT](https://upstash.com/docs/redis/sdks/ts/commands/hash/hexpireat.md): Sets an expiration time for field(s) in a hash in seconds since the Unix epoch.
- [HEXPIRETIME](https://upstash.com/docs/redis/sdks/ts/commands/hash/hexpiretime.md): Retrieves the expiration time of field(s) in a hash in seconds.
- [HGET](https://upstash.com/docs/redis/sdks/ts/commands/hash/hget.md): Retrieves the value of a hash field.
- [HGETALL](https://upstash.com/docs/redis/sdks/ts/commands/hash/hgetall.md): Retrieves all fields from a hash.
- [HGETDEL](https://upstash.com/docs/redis/sdks/ts/commands/hash/hgetdel.md): Get and delete hash fields atomically.
- [HGETEX](https://upstash.com/docs/redis/sdks/ts/commands/hash/hgetex.md): Get hash fields with expiration support.
- [HINCRBY](https://upstash.com/docs/redis/sdks/ts/commands/hash/hincrby.md): Increments the value of a hash field by a given amount
- [HINCRBYFLOAT](https://upstash.com/docs/redis/sdks/ts/commands/hash/hincrbyfloat.md): Increments the value of a hash field by a given float value.
- [HKEYS](https://upstash.com/docs/redis/sdks/ts/commands/hash/hkeys.md): Return all field names in the hash stored at key.
- [HLEN](https://upstash.com/docs/redis/sdks/ts/commands/hash/hlen.md): Returns the number of fields contained in the hash stored at key.
- [HMGET](https://upstash.com/docs/redis/sdks/ts/commands/hash/hmget.md): Return the requested fields and their values.
- [HPERSIST](https://upstash.com/docs/redis/sdks/ts/commands/hash/hpersist.md): Remove the expiration from one or more fields in a hash.
- [HPEXPIRE](https://upstash.com/docs/redis/sdks/ts/commands/hash/hpexpire.md): Sets an expiration time for a field in a hash in milliseconds.
- [HPEXPIREAT](https://upstash.com/docs/redis/sdks/ts/commands/hash/hpexpireat.md): Sets an expiration time for field(s) in a hash in milliseconds since the Unix epoch.
- [HPEXPIRETIME](https://upstash.com/docs/redis/sdks/ts/commands/hash/hpexpiretime.md): Retrieves the expiration time of a field in a hash in milliseconds.
- [HPTTL](https://upstash.com/docs/redis/sdks/ts/commands/hash/hpttl.md): Retrieves the remaining time-to-live (TTL) for field(s) in a hash in milliseconds.
- [HRANDFIELD](https://upstash.com/docs/redis/sdks/ts/commands/hash/hrandfield.md): Return a random field from a hash
- [HSCAN](https://upstash.com/docs/redis/sdks/ts/commands/hash/hscan.md): Scan a hash for fields.
- [HSET](https://upstash.com/docs/redis/sdks/ts/commands/hash/hset.md): Write one or more fields to a hash.
- [HSETEX](https://upstash.com/docs/redis/sdks/ts/commands/hash/hsetex.md): Set hash fields with expiration support.
- [HSETNX](https://upstash.com/docs/redis/sdks/ts/commands/hash/hsetnx.md): Write a field to a hash but only if the field does not exist.
- [HSTRLEN](https://upstash.com/docs/redis/sdks/ts/commands/hash/hstrlen.md): Returns the string length of a value in a hash.
- [HTTL](https://upstash.com/docs/redis/sdks/ts/commands/hash/httl.md): Retrieves the remaining time-to-live (TTL) for field(s) in a hash in seconds.
- [HVALS](https://upstash.com/docs/redis/sdks/ts/commands/hash/hvals.md): Returns all values in the hash stored at key.
- [JSON.ARRAPPEND](https://upstash.com/docs/redis/sdks/ts/commands/json/arrappend.md): Append values to the array at path in the JSON document at key.
- [JSON.ARRINDEX](https://upstash.com/docs/redis/sdks/ts/commands/json/arrindex.md): Search for the first occurrence of a JSON value in an array.
- [JSON.ARRINSERT](https://upstash.com/docs/redis/sdks/ts/commands/json/arrinsert.md): Insert the json values into the array at path before the index (shifts to the right).
- [JSON.ARRLEN](https://upstash.com/docs/redis/sdks/ts/commands/json/arrlen.md): Report the length of the JSON array at `path` in `key`.
- [JSON.ARRPOP](https://upstash.com/docs/redis/sdks/ts/commands/json/arrpop.md): Remove and return an element from the index in the array. By default the last element from an array is popped.
- [JSON.ARRTRIM](https://upstash.com/docs/redis/sdks/ts/commands/json/arrtrim.md): Trim an array so that it contains only the specified inclusive range of elements.
- [JSON.CLEAR](https://upstash.com/docs/redis/sdks/ts/commands/json/clear.md): Clear container values (arrays/objects) and set numeric values to 0.
- [JSON.DEL](https://upstash.com/docs/redis/sdks/ts/commands/json/del.md): Delete a key from a JSON document.
- [JSON.FORGET](https://upstash.com/docs/redis/sdks/ts/commands/json/forget.md): Delete a key from a JSON document.
- [JSON.GET](https://upstash.com/docs/redis/sdks/ts/commands/json/get.md): Get a single value from a JSON document.
- [JSON.MERGE](https://upstash.com/docs/redis/sdks/ts/commands/json/merge.md): Merges the JSON value at path in key with the provided value.
- [JSON.MGET](https://upstash.com/docs/redis/sdks/ts/commands/json/mget.md): Get the same path from multiple JSON documents.
- [JSON.MSET](https://upstash.com/docs/redis/sdks/ts/commands/json/mset.md): Sets multiple JSON values at multiple paths in multiple keys.
- [JSON.NUMINCRBY](https://upstash.com/docs/redis/sdks/ts/commands/json/numincrby.md): Increment the number value stored at `path` by number.
- [JSON.NUMMULTBY](https://upstash.com/docs/redis/sdks/ts/commands/json/nummultby.md): Multiply the number value stored at `path` by number.
- [JSON.OBJKEYS](https://upstash.com/docs/redis/sdks/ts/commands/json/objkeys.md): Return the keys in the object that`s referenced by path.
- [JSON.OBJLEN](https://upstash.com/docs/redis/sdks/ts/commands/json/objlen.md): Report the number of keys in the JSON object at `path` in `key`.
- [JSON.SET](https://upstash.com/docs/redis/sdks/ts/commands/json/set.md): Set the JSON value at path in key.
- [JSON.STRAPPEND](https://upstash.com/docs/redis/sdks/ts/commands/json/strappend.md): Append the json-string values to the string at path.
- [JSON.STRLEN](https://upstash.com/docs/redis/sdks/ts/commands/json/strlen.md): Report the length of the JSON String at path in key
- [JSON.TOGGLE](https://upstash.com/docs/redis/sdks/ts/commands/json/toggle.md): Toggle a boolean value stored at `path`.
- [JSON.TYPE](https://upstash.com/docs/redis/sdks/ts/commands/json/type.md): Report the type of JSON value at `path`.
- [LINDEX](https://upstash.com/docs/redis/sdks/ts/commands/list/lindex.md): Returns the element at index index in the list stored at key.
- [LINSERT](https://upstash.com/docs/redis/sdks/ts/commands/list/linsert.md): Insert an element before or after another element in a list
- [LLEN](https://upstash.com/docs/redis/sdks/ts/commands/list/llen.md): Returns the length of the list stored at key.
- [LMOVE](https://upstash.com/docs/redis/sdks/ts/commands/list/lmove.md): Move an element from one list to another.
- [LPOP](https://upstash.com/docs/redis/sdks/ts/commands/list/lpop.md): Remove and return the first element(s) of a list
- [LPOS](https://upstash.com/docs/redis/sdks/ts/commands/list/lpos.md): Returns the index of matching elements inside a list.
- [LPUSH](https://upstash.com/docs/redis/sdks/ts/commands/list/lpush.md): Push an element at the head of the list.
- [LPUSHX](https://upstash.com/docs/redis/sdks/ts/commands/list/lpushx.md): Push an element at the head of the list only if the list exists.
- [LRANGE](https://upstash.com/docs/redis/sdks/ts/commands/list/lrange.md): Returns the specified elements of the list stored at key.
- [LREM](https://upstash.com/docs/redis/sdks/ts/commands/list/lrem.md): Remove the first `count` occurrences of an element from a list.
- [LSET](https://upstash.com/docs/redis/sdks/ts/commands/list/lset.md): Set a value at a specific index.
- [LTRIM](https://upstash.com/docs/redis/sdks/ts/commands/list/ltrim.md): Trim a list to the specified range
- [RPOP](https://upstash.com/docs/redis/sdks/ts/commands/list/rpop.md): Remove and return the last element(s) of a list
- [RPUSH](https://upstash.com/docs/redis/sdks/ts/commands/list/rpush.md): Push an element at the end of the list.
- [RPUSHX](https://upstash.com/docs/redis/sdks/ts/commands/list/rpushx.md): Push an element at the end of the list only if the list exists.
- [Overview](https://upstash.com/docs/redis/sdks/ts/commands/overview.md): Available Commands in @upstash/redis
- [PSUBSCRIBE](https://upstash.com/docs/redis/sdks/ts/commands/pubsub/psubscribe.md): Subscribe to a channel by patterns/wildcards
- [PUBLISH](https://upstash.com/docs/redis/sdks/ts/commands/pubsub/publish.md): Publish a message to a channel
- [SUBSCRIBE](https://upstash.com/docs/redis/sdks/ts/commands/pubsub/subscribe.md): Subscribe to a channel
- [EVAL](https://upstash.com/docs/redis/sdks/ts/commands/scripts/eval.md): Evaluate a Lua script server side.
- [EVAL_RO](https://upstash.com/docs/redis/sdks/ts/commands/scripts/eval_ro.md): Evaluate a read-only Lua script server side.
- [EVALSHA](https://upstash.com/docs/redis/sdks/ts/commands/scripts/evalsha.md): Evaluate a cached Lua script server side.
- [EVALSHA_RO](https://upstash.com/docs/redis/sdks/ts/commands/scripts/evalsha_ro.md): Evaluate a cached read-only Lua script server side.
- [SCRIPT EXISTS](https://upstash.com/docs/redis/sdks/ts/commands/scripts/script_exists.md): Check if scripts exist in the script cache.
- [SCRIPT FLUSH](https://upstash.com/docs/redis/sdks/ts/commands/scripts/script_flush.md): Removes all scripts from the script cache.
- [SCRIPT LOAD](https://upstash.com/docs/redis/sdks/ts/commands/scripts/script_load.md): Load the specified Lua script into the script cache.
- [DBSIZE](https://upstash.com/docs/redis/sdks/ts/commands/server/dbsize.md): Count the number of keys in the database.
- [FLUSHALL](https://upstash.com/docs/redis/sdks/ts/commands/server/flushall.md)
- [FLUSHDB](https://upstash.com/docs/redis/sdks/ts/commands/server/flushdb.md)
- [SADD](https://upstash.com/docs/redis/sdks/ts/commands/set/sadd.md): Adds one or more members to a set.
- [SCARD](https://upstash.com/docs/redis/sdks/ts/commands/set/scard.md): Return how many members are in a set
- [SDIFF](https://upstash.com/docs/redis/sdks/ts/commands/set/sdiff.md): Return the difference between sets
- [SDIFFSTORE](https://upstash.com/docs/redis/sdks/ts/commands/set/sdiffstore.md): Write the difference between sets to a new set
- [SINTER](https://upstash.com/docs/redis/sdks/ts/commands/set/sinter.md): Return the intersection between sets
- [SINTERSTORE](https://upstash.com/docs/redis/sdks/ts/commands/set/sinterstore.md): Return the intersection between sets and store the resulting set in a key
- [SISMEMBER](https://upstash.com/docs/redis/sdks/ts/commands/set/sismember.md): Check if a member exists in a set
- [SMEMBERS](https://upstash.com/docs/redis/sdks/ts/commands/set/smembers.md): Return all the members of a set
- [SMISMEMBER](https://upstash.com/docs/redis/sdks/ts/commands/set/smismember.md): Check if multiple members exist in a set
- [SMOVE](https://upstash.com/docs/redis/sdks/ts/commands/set/smove.md): Move a member from one set to another
- [SPOP](https://upstash.com/docs/redis/sdks/ts/commands/set/spop.md): Removes and returns one or more random members from a set.
- [SRANDMEMBER](https://upstash.com/docs/redis/sdks/ts/commands/set/srandmember.md): Returns one or more random members from a set.
- [SREM](https://upstash.com/docs/redis/sdks/ts/commands/set/srem.md): Remove one or more members from a set
- [SSCAN](https://upstash.com/docs/redis/sdks/ts/commands/set/sscan.md): Scan a set
- [SUNION](https://upstash.com/docs/redis/sdks/ts/commands/set/sunion.md): Return the union between sets
- [SUNIONSTORE](https://upstash.com/docs/redis/sdks/ts/commands/set/sunionstore.md): Return the union between sets and store the resulting set in a key
- [XACK](https://upstash.com/docs/redis/sdks/ts/commands/stream/xack.md): Removes one or multiple messages from the pending entries list of a stream consumer group.
- [XACKDEL](https://upstash.com/docs/redis/sdks/ts/commands/stream/xackdel.md): Acknowledge and delete stream entries atomically.
- [XADD](https://upstash.com/docs/redis/sdks/ts/commands/stream/xadd.md): Appends one or more new entries to a stream.
- [XAUTOCLAIM](https://upstash.com/docs/redis/sdks/ts/commands/stream/xautoclaim.md): Changes the ownership of pending messages from one consumer to another in a stream consumer group.
- [XCLAIM](https://upstash.com/docs/redis/sdks/ts/commands/stream/xclaim.md): Changes the ownership of pending messages from one consumer to another in a stream consumer group.
- [XDEL](https://upstash.com/docs/redis/sdks/ts/commands/stream/xdel.md): Removes the specified entries from a stream, and returns the number of entries deleted.
- [XDELEX](https://upstash.com/docs/redis/sdks/ts/commands/stream/xdelex.md): Extended delete for streams with reference control.
- [XGROUP](https://upstash.com/docs/redis/sdks/ts/commands/stream/xgroup.md): Manage consumer groups for Redis streams.
- [XINFO](https://upstash.com/docs/redis/sdks/ts/commands/stream/xinfo.md): Returns information about streams, consumer groups, and consumers.
- [XLEN](https://upstash.com/docs/redis/sdks/ts/commands/stream/xlen.md): Returns the number of entries inside a stream.
- [XPENDING](https://upstash.com/docs/redis/sdks/ts/commands/stream/xpending.md): Returns information about pending messages in a stream consumer group.
- [XRANGE](https://upstash.com/docs/redis/sdks/ts/commands/stream/xrange.md): Returns stream entries matching a given range of IDs.
- [XREAD](https://upstash.com/docs/redis/sdks/ts/commands/stream/xread.md): Reads data from one or multiple streams, starting from the specified IDs.
- [XREADGROUP](https://upstash.com/docs/redis/sdks/ts/commands/stream/xreadgroup.md): Reads data from a stream as part of a consumer group.
- [XREVRANGE](https://upstash.com/docs/redis/sdks/ts/commands/stream/xrevrange.md): Returns stream entries matching a given range of IDs in reverse order.
- [XTRIM](https://upstash.com/docs/redis/sdks/ts/commands/stream/xtrim.md): Trims the stream by removing entries to keep it at a reasonable size.
- [String Commands](https://upstash.com/docs/redis/sdks/ts/commands/string.md)
- [APPEND](https://upstash.com/docs/redis/sdks/ts/commands/string/append.md): Append a value to a string stored at key.
- [DECR](https://upstash.com/docs/redis/sdks/ts/commands/string/decr.md): Decrement the integer value of a key by one
- [DECRBY](https://upstash.com/docs/redis/sdks/ts/commands/string/decrby.md): Decrement the integer value of a key by a given number.
- [GET](https://upstash.com/docs/redis/sdks/ts/commands/string/get.md): Return the value of the specified key or `null` if the key doesn't exist.
- [GETDEL](https://upstash.com/docs/redis/sdks/ts/commands/string/getdel.md): Return the value of the specified key and delete the key.
- [GETRANGE](https://upstash.com/docs/redis/sdks/ts/commands/string/getrange.md): Return a substring of value at the specified key.
- [GETSET](https://upstash.com/docs/redis/sdks/ts/commands/string/getset.md): Return the value of the specified key and replace it with a new value.
- [INCR](https://upstash.com/docs/redis/sdks/ts/commands/string/incr.md): Increment the integer value of a key by one
- [INCRBY](https://upstash.com/docs/redis/sdks/ts/commands/string/incrby.md): Increment the integer value of a key by a given number.
- [INCRBYFLOAT](https://upstash.com/docs/redis/sdks/ts/commands/string/incrbyfloat.md): Increment the float value of a key by a given number.
- [MGET](https://upstash.com/docs/redis/sdks/ts/commands/string/mget.md): Load multiple keys from Redis in one go.
- [MSET](https://upstash.com/docs/redis/sdks/ts/commands/string/mset.md): Set multiple keys in one go.
- [MSETNX](https://upstash.com/docs/redis/sdks/ts/commands/string/msetnx.md): Set multiple keys in one go unless they exist already.
- [SET](https://upstash.com/docs/redis/sdks/ts/commands/string/set.md): Set a key to hold a string value.
- [SETRANGE](https://upstash.com/docs/redis/sdks/ts/commands/string/setrange.md): Writes the value of key at offset.
- [STRLEN](https://upstash.com/docs/redis/sdks/ts/commands/string/strlen.md): Return the length of a string stored at a key.
- [Transactions](https://upstash.com/docs/redis/sdks/ts/commands/transaction.md): Transactions
- [ZADD](https://upstash.com/docs/redis/sdks/ts/commands/zset/zadd.md): Add a member to a sorted set, or update its score if it already exists.
- [ZCARD](https://upstash.com/docs/redis/sdks/ts/commands/zset/zcard.md): Returns the number of elements in the sorted set stored at key.
- [ZCOUNT](https://upstash.com/docs/redis/sdks/ts/commands/zset/zcount.md): Returns the number of elements in the sorted set stored at key filterd by score.
- [ZDIFFSTORE](https://upstash.com/docs/redis/sdks/ts/commands/zset/zdiffstore.md): Writes the difference between sets to a new key.
- [ZINCRBY](https://upstash.com/docs/redis/sdks/ts/commands/zset/zincrby.md): Increment the score of a member.
- [ZINTERSTORE](https://upstash.com/docs/redis/sdks/ts/commands/zset/zinterstore.md): Writes the intersection between sets to a new key.
- [ZLEXCOUNT](https://upstash.com/docs/redis/sdks/ts/commands/zset/zlexcount.md): Returns the number of elements in the sorted set stored at key filtered by lex.
- [ZMSCORE](https://upstash.com/docs/redis/sdks/ts/commands/zset/zmscore.md): Returns the scores of multiple members.
- [ZPOPMAX](https://upstash.com/docs/redis/sdks/ts/commands/zset/zpopmax.md): Removes and returns up to count members with the highest scores in the sorted set stored at key.
- [ZPOPMIN](https://upstash.com/docs/redis/sdks/ts/commands/zset/zpopmin.md): Removes and returns up to count members with the lowest scores in the sorted set stored at key.
- [ZRANGE](https://upstash.com/docs/redis/sdks/ts/commands/zset/zrange.md): Returns the specified range of elements in the sorted set stored at key.
- [ZRANK](https://upstash.com/docs/redis/sdks/ts/commands/zset/zrank.md): Returns the rank of a member
- [ZREM](https://upstash.com/docs/redis/sdks/ts/commands/zset/zrem.md): Remove one or more members from a sorted set
- [ZREMRANGEBYLEX](https://upstash.com/docs/redis/sdks/ts/commands/zset/zremrangebylex.md): Remove all members in a sorted set between the given lexicographical range.
- [ZREMRANGEBYRANK](https://upstash.com/docs/redis/sdks/ts/commands/zset/zremrangebyrank.md): Remove all members in a sorted set between the given ranks.
- [ZREMRANGEBYSCORE](https://upstash.com/docs/redis/sdks/ts/commands/zset/zremrangebyscore.md): Remove all members in a sorted set between the given scores.
- [ZREVRANK](https://upstash.com/docs/redis/sdks/ts/commands/zset/zrevrank.md): Returns the rank of a member in a sorted set, with scores ordered from high to low.
- [ZSCAN](https://upstash.com/docs/redis/sdks/ts/commands/zset/zscan.md): Scan a sorted set
- [ZSCORE](https://upstash.com/docs/redis/sdks/ts/commands/zset/zscore.md): Returns the scores of a member.
- [ZUNIONSTORE](https://upstash.com/docs/redis/sdks/ts/commands/zset/zunionstore.md): Writes the union between sets to a new key.

# 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: <UPSTASH_REDIS_REST_URL>,
  token: <UPSTASH_REDIS_REST_TOKEN>,
})

// or load directly from env
const redis = Redis.fromEnv()
```

<Info>
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";
```

</Info>

* [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: <UPSTASH_REDIS_REST_URL>,
  token: <UPSTASH_REDIS_REST_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: <UPSTASH_REDIS_REST_URL>,
  token: <UPSTASH_REDIS_REST_TOKEN>,
  backend: <BACKEND_NAME>,
})
```

* [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: <UPSTASH_REDIS_REST_URL>,
  token: <UPSTASH_REDIS_REST_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: <UPSTASH_REDIS_REST_URL>,
  token: <UPSTASH_REDIS_REST_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](https://github.com/upstash/redis-js)
is an HTTP/REST based Redis client built on top of
[Upstash REST API](/docs/redis/features/restapi).

[![Tests]()](https://github.com/upstash/redis-js/actions/workflows/tests.yaml)
![npm (scoped)]()
![npm bundle size]()

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/redis-js/tree/main/examples/cloudflare-workers))
* Fastly Compute@Edge (see
  [the example](https://github.com/upstash/redis-js/tree/main/examples/fastly))
* Next.js (see [the quickstart](/docs/redis/quickstarts/nextjs-app-router)), Jamstack
* Client side web/mobile applications
* WebAssembly
* and other environments where HTTP is preferred over TCP.

See
[the list of APIs](/docs/redis/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.

This feature is enabled by default. To disable it, simply pass `enableAutoPipelining: false`
when creating the Redis client:

```ts Redis
import { Redis } from "@upstash/redis";

const redis = Redis.fromEnv({
  enableAutoPipelining: false
});
```

```ts fromEnv
import { Redis } from "@upstash/redis";

const redis = new Redis({
  url: <UPSTASH_REDIS_REST_URL>,
  token: <UPSTASH_REDIS_REST_TOKEN>,
  enableAutoPipelining: true
})
```
</CodeGroup>

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.

# ioredis
Source: https://upstash.com/docs/redis/search/adapters/ioredis

If you're already using **ioredis** in your project, you can use Redis Search without switching to the `@upstash/redis` client. The `@upstash/search-ioredis` package wraps your existing ioredis instance and exposes the full Redis Search API.

### Installation

```bash
npm install @upstash/search-ioredis ioredis
```

### Setup

```ts
import IORedis from "ioredis";
import { createSearch, s } from "@upstash/search-ioredis";

// Create ioredis client using your Upstash Redis URL
const ioredis = new IORedis(process.env.REDIS_URL);

// Create search client
const search = createSearch(ioredis);
```

The `REDIS_URL` should be your Upstash Redis connection string in the format:

```
rediss://default:<PASSWORD>@<YOUR-DATABASE>.upstash.io:6379
```

### Create an Index

```ts
const schema = s.object({
  name: s.string(),
  description: s.string(),
  category: s.string().noTokenize(),
  price: s.number(),
  inStock: s.boolean(),
});

await search.createIndex({
  name: "products",
  dataType: "json",
  prefix: "product:",
  schema,
});
```

### Get an Index Client

Use `search.index()` to get a client for an existing index without making a Redis call:

```ts
const index = search.index({ name: "products", schema });
```

### Add Data

Add data using standard Redis commands via your ioredis client. Any key matching the index prefix is automatically indexed:

```ts
await ioredis.call("JSON.SET", "product:1", "$", JSON.stringify({
  name: "Wireless Headphones",
  description: "Premium noise-cancelling wireless headphones with 30-hour battery life",
  category: "electronics",
  price: 199.99,
  inStock: true,
}));
```

### Search Data

```ts
// Query with a filter
const results = await index.query({
  filter: { description: "wireless" },
});

// Count matching documents
const count = await index.count({
  filter: { price: { $lt: 150 } },
});
```

### Wait for Indexing

Index updates are batched for performance. Use `waitIndexing()` when you need queries to reflect recent writes:

```ts
await index.waitIndexing();
```

### Describe an Index

```ts
const description = await index.describe();
```

### Drop an Index

```ts
const result = await index.drop();
// Returns 1 (dropped) or 0 (index not found)
```

<Note>
The adapter exposes the exact same search API as `@upstash/redis`. Refer to the [Index Management](../index-management), [Querying](../querying), [Aggregations](../aggregations), and [Schema Definition](../schema-definition) pages for the full API reference.
</Note>

# node-redis
Source: https://upstash.com/docs/redis/search/adapters/node-redis

If you're already using **node-redis** in your project, you can use Redis Search without switching to the `@upstash/redis` client. The `@upstash/search-redis` package wraps your existing node-redis client and exposes the full Redis Search API.

### Installation

```bash
npm install @upstash/search-redis redis
```

### Setup

```ts
import { createClient } from "redis";
import { createSearch, s } from "@upstash/search-redis";

// Create node-redis client using your Upstash Redis URL
const client = createClient({
  url: process.env.REDIS_URL,
});
await client.connect();

// Create search client
const search = createSearch(client);
```

The `REDIS_URL` should be your Upstash Redis connection string in the format:

```
rediss://default:<PASSWORD>@<YOUR-DATABASE>.upstash.io:6379
```

### Create an Index

```ts
const schema = s.object({
  name: s.string(),
  description: s.string(),
  category: s.string().noTokenize(),
  price: s.number(),
  inStock: s.boolean(),
});

await search.createIndex({
  name: "products",
  dataType: "json",
  prefix: "product:",
  schema,
});
```

### Get an Index Client

Use `search.index()` to get a client for an existing index without making a Redis call:

```ts
const index = search.index({ name: "products", schema });
```

### Add Data

Add data using standard Redis commands via your node-redis client. Any key matching the index prefix is automatically indexed:

```ts
await client.sendCommand(["JSON.SET", "product:1", "$", JSON.stringify({
  name: "Wireless Headphones",
  description: "Premium noise-cancelling wireless headphones with 30-hour battery life",
  category: "electronics",
  price: 199.99,
  inStock: true,
})]);
```

### Search Data

```ts
// Query with a filter
const results = await index.query({
  filter: { description: "wireless" },
});

// Count matching documents
const count = await index.count({
  filter: { price: { $lt: 150 } },
});
```

### Wait for Indexing

Index updates are batched for performance. Use `waitIndexing()` when you need queries to reflect recent writes:

```ts
await index.waitIndexing();
```

### Describe an Index

```ts
const description = await index.describe();
```

### Drop an Index

```ts
const result = await index.drop();
// Returns 1 (dropped) or 0 (index not found)
```

# $dateHistogram
Source: https://upstash.com/docs/redis/search/aggregation-operators/bucket-aggregations/date-histogram

`$dateHistogram` groups date values into fixed time buckets.

Use it for time-series analytics like events per hour/day.

### Compatibility

| Field Type | Supported |
|------------|-----------|
| TEXT | No |
| U64/I64/F64 | No |
| DATE | Yes |
| BOOL | No |
| KEYWORD | No |
| FACET | No |

Field must be `FAST`.

### Arguments

| Argument | Type | Required | Description |
|----------|------|----------|-------------|
| `field` | `string` | Yes | Date field to bucket on. |
| `fixedInterval` | `string` | Yes | Interval string such as `"1m"`, `"1h"`, `"1d"`. |
| `offset` | `string` | No | Shift bucket boundaries. |
| `minDocCount` | `number` | No | Exclude buckets with fewer docs. |
| `hardBounds` | `{ min: number, max: number }` | No | Hard clamp for bucket range. |
| `extendedBounds` | `{ min: number, max: number }` | No | Emit buckets across this range, including empty ones. |
| `keyed` | `boolean` | No | If `true`, returns buckets as an object. Default: `false`. |

For `hardBounds` and `extendedBounds`, both `min` and `max` are required.

<Tabs>

<Tab title="TypeScript">
```ts
await index.aggregate({
  aggregations: {
    by_day: {
      $dateHistogram: {
        field: "createdAt",
        fixedInterval: "1d",
      },
    },
  },
});
```
</Tab>

<Tab title="Python">
```python
index.aggregate(
    aggregations={
        "by_day": {
            "$dateHistogram": {
                "field": "createdAt",
                "fixedInterval": "1d",
            }
        }
    }
)
```
</Tab>

<Tab title="Redis CLI">
```bash
SEARCH.AGGREGATE logs '{}' '{"by_day": {"$dateHistogram": {"field": "createdAt", "fixedInterval": "1d"}}}'
```
</Tab>

</Tabs>

### Output

```json
{
  "by_day": {
    "buckets": [
      { "key": 1704067200000, "keyAsString": "2024-01-01T00:00:00Z", "docCount": 14 },
      { "key": 1704153600000, "keyAsString": "2024-01-02T00:00:00Z", "docCount": 9 }
    ]
  }
}
```

# $facet
Source: https://upstash.com/docs/redis/search/aggregation-operators/bucket-aggregations/facet

`$facet` builds a hierarchical bucket tree from FACET field paths.

Use it for category navigation and drill-down style faceting.

### Compatibility

| Field Type | Supported |
|------------|-----------|
| TEXT | No |
| U64/I64/F64 | No |
| DATE | No |
| BOOL | No |
| KEYWORD | No |
| FACET | Yes |

### Arguments

| Argument | Type | Required | Description |
|----------|------|----------|-------------|
| `field` | `string` | Yes | FACET field name. |
| `path` | `string` | Yes | Root path to expand. Must start with `/`. |
| `depth` | `number` | No | Levels to traverse (`>= 1`). Default: `1`. |
| `size` | `number` | No | Max children per level. Default: `10`. |
| `minDocCount` | `number` | No | Minimum docs required for a child bucket. Default: `1`. |
| `order` | `object` | No | One-key order object: `{ "count": "asc\|desc" }` or `{ "path": "asc\|desc" }`. Default: `{ "count": "desc" }`. |

<Tabs>

<Tab title="TypeScript">
```ts
await index.aggregate({
  aggregations: {
    by_category: {
      $facet: {
        field: "category",
        path: "/category",
      },
    },
  },
});
```
</Tab>

<Tab title="Python">
```python
index.aggregate(
    aggregations={
        "by_category": {
            "$facet": {
                "field": "category",
                "path": "/category",
            }
        }
    }
)
```
</Tab>

<Tab title="Redis CLI">
```bash
SEARCH.AGGREGATE products '{}' '{"by_category": {"$facet": {"field": "category", "path": "/category"}}}'
```
</Tab>

</Tabs>

### Output

```json
{
  "by_category": {
    "path": "/category",
    "sumOtherDocCount": 0,
    "children": [
      { "path": "/category/books", "docCount": 12, "sumOtherDocCount": 0 },
      { "path": "/category/electronics", "docCount": 9, "sumOtherDocCount": 0 }
    ]
  }
}
```

* Increase `depth` for multi-level facet trees.
* Use `size` and `minDocCount` to control noise and response size.
* Use `order` to sort by count or by path.

<Tabs>

<Tab title="TypeScript">
```ts
await index.aggregate({
  aggregations: {
    category_tree: {
      $facet: {
        field: "category",
        path: "/category",
        depth: 2,
        size: 10,
        minDocCount: 1,
        order: { count: "desc" },
      },
    },
  },
});
```
</Tab>

<Tab title="Python">
```python
index.aggregate(
    aggregations={
        "category_tree": {
            "$facet": {
                "field": "category",
                "path": "/category",
                "depth": 2,
                "size": 10,
                "minDocCount": 1,
                "order": {"count": "desc"},
            }
        }
    }
)
```
</Tab>

<Tab title="Redis CLI">
```bash
SEARCH.AGGREGATE products '{}' '{"category_tree": {"$facet": {"field": "category", "path": "/category", "depth": 2, "size": 10, "minDocCount": 1, "order": {"count": "desc"}}}}'
```
</Tab>

</Tabs>

With `depth: 2`, the response includes nested children:

```json
{
  "by_cat": {
    "path": "/category",
    "sumOtherDocCount": 0,
    "children": [
      {
        "docCount": 2,
        "path": "/category/books",
        "sumOtherDocCount": 0,
        "children": [
          { "docCount": 1, "path": "/category/books/fiction", "sumOtherDocCount": 0 },
          { "docCount": 1, "path": "/category/books/nonfiction", "sumOtherDocCount": 0 }
        ]
      },
      {
        "docCount": 2,
        "path": "/category/electronics",
        "sumOtherDocCount": 0,
        "children": [
          { "docCount": 1, "path": "/category/electronics/laptops", "sumOtherDocCount": 0 },
          { "docCount": 1, "path": "/category/electronics/phones", "sumOtherDocCount": 0 }
        ]
      }
    ]
  }
}
```

* `$facet` cannot contain `$aggs`.
* `$facet` cannot be used as a sub-aggregation inside another `$aggs` block.

# $histogram
Source: https://upstash.com/docs/redis/search/aggregation-operators/bucket-aggregations/histogram

`$histogram` groups numeric values into fixed-width interval buckets.

Use it for distribution charts when each bucket has the same width.

### Compatibility

| Field Type | Supported |
|------------|-----------|
| TEXT | No |
| U64/I64/F64 | Yes |
| DATE | Yes |
| BOOL | No |
| KEYWORD | No |
| FACET | No |

Field must be `FAST`.

### Arguments

| Argument | Type | Required | Description |
|----------|------|----------|-------------|
| `field` | `string` | Yes | Field to bucket on. |
| `interval` | `number` | Yes | Bucket width. |
| `offset` | `number` | No | Shift bucket boundaries. |
| `minDocCount` | `number` | No | Exclude buckets with fewer docs. |
| `hardBounds` | `{ min: number, max: number }` | No | Hard clamp for bucket range. |
| `extendedBounds` | `{ min: number, max: number }` | No | Emit buckets across this range, including empty ones. |
| `keyed` | `boolean` | No | If `true`, returns buckets as an object. Default: `false`. |

For `hardBounds` and `extendedBounds`, both `min` and `max` are required.

<Tabs>

<Tab title="TypeScript">
```ts
await index.aggregate({
  aggregations: {
    price_distribution: {
      $histogram: { field: "price", interval: 25 },
    },
  },
});
```
</Tab>

<Tab title="Python">
```python
index.aggregate(
    aggregations={
        "price_distribution": {
            "$histogram": {"field": "price", "interval": 25}
        }
    }
)
```
</Tab>

<Tab title="Redis CLI">
```bash
SEARCH.AGGREGATE products '{}' '{"price_distribution": {"$histogram": {"field": "price", "interval": 25}}}'
```
</Tab>

</Tabs>

### Output

```json
{
  "price_distribution": {
    "buckets": [
      { "key": 0, "docCount": 3 },
      { "key": 25, "docCount": 4 },
      { "key": 50, "docCount": 2 }
    ]
  }
}
```

Bucket entries can include `keyAsString` and nested sub-aggregation outputs.

# Overview
Source: https://upstash.com/docs/redis/search/aggregation-operators/bucket-aggregations/overview

Bucket aggregations group matching documents into buckets.

Use bucket aggregations when you want segmented analytics (for example by category, price tier, or time window).

### Available Operators

| Operator | What it groups by |
|----------|-------------------|
| [`$terms`](./terms) | Distinct field values |
| [`$range`](./range) | Explicit `from` / `to` ranges |
| [`$histogram`](./histogram) | Fixed numeric intervals |
| [`$dateHistogram`](./date-histogram) | Fixed date/time intervals |
| [`$facet`](./facet) | Hierarchical FACET paths |

### Input Format

Every bucket operator takes an object with a `field` property and operator-specific parameters:

**`$terms`** — group by distinct values:
```json
{"by_category": {"$terms": {"field": "category", "size": 10}}}
```

**`$range`** — custom range buckets:
```json
{"price_ranges": {"$range": {"field": "price", "ranges": [{"to": 50}, {"from": 50, "to": 100}, {"from": 100}]}}}
```

**`$histogram`** — fixed numeric intervals:
```json
{"price_buckets": {"$histogram": {"field": "price", "interval": 10}}}
```

**`$dateHistogram`** — fixed time intervals:
```json
{"by_month": {"$dateHistogram": {"field": "createdAt", "fixedInterval": "30d"}}}
```

### Behavior Notes

* Bucket operators can contain nested `$aggs` for per-bucket metrics.
* `$terms`, `$range`, `$histogram`, and `$dateHistogram` support nested `$aggs`.
* `$facet` does not support nested `$aggs` and cannot be used as a sub-aggregation.

# $range
Source: https://upstash.com/docs/redis/search/aggregation-operators/bucket-aggregations/range

`$range` groups documents into custom ranges.

Use it when bucket boundaries are defined by business logic (for example pricing tiers).

### Compatibility

| Field Type | Supported |
|------------|-----------|
| TEXT | No |
| U64/I64/F64 | Yes |
| DATE | Yes |
| BOOL | No |
| KEYWORD | No |
| FACET | No |

Field must be `FAST`.

### Arguments

| Argument | Type | Required | Description |
|----------|------|----------|-------------|
| `field` | `string` | Yes | Field to bucket on. |
| `ranges` | `Array<{ key?: string, from?: number, to?: number }>` | Yes | Non-empty array of range objects. |
| `keyed` | `boolean` | No | If `true`, returns buckets as an object. Default: `false`. |

`from` is inclusive. `to` is exclusive.

<Tabs>

<Tab title="TypeScript">
```ts
await index.aggregate({
  aggregations: {
    price_tiers: {
      $range: {
        field: "price",
        ranges: [{ to: 30 }, { from: 30, to: 60 }, { from: 60 }],
      },
    },
  },
});
```
</Tab>

<Tab title="Python">
```python
index.aggregate(
    aggregations={
        "price_tiers": {
            "$range": {
                "field": "price",
                "ranges": [{"to": 30}, {"from": 30, "to": 60}, {"from": 60}],
            }
        }
    }
)
```
</Tab>

<Tab title="Redis CLI">
```bash
SEARCH.AGGREGATE products '{}' '{"price_tiers": {"$range": {"field": "price", "ranges": [{"to": 30}, {"from": 30, "to": 60}, {"from": 60}]}}}'
```
</Tab>

</Tabs>

### Output

```json
{
  "price_tiers": {
    "buckets": [
      { "key": "*-30", "docCount": 3, "to": 30 },
      { "key": "30-60", "docCount": 3, "from": 30, "to": 60 },
      { "key": "60-*", "docCount": 3, "from": 60 }
    ]
  }
}
```

Bucket entries can include `fromAsString` / `toAsString` and nested sub-aggregation outputs.

# $terms
Source: https://upstash.com/docs/redis/search/aggregation-operators/bucket-aggregations/terms

`$terms` groups documents by distinct field values.

Each distinct value becomes one bucket with its own `docCount`.

### Compatibility

| Field Type | Supported |
|------------|-----------|
| TEXT | No |
| U64/I64/F64 | Yes |
| DATE | Yes |
| BOOL | Yes |
| KEYWORD | Yes |
| FACET | No |

Field must be `FAST`.

### Arguments

| Argument | Type | Required | Description |
|----------|------|----------|-------------|
| `field` | `string` | Yes | Field to bucket on. |
| `size` | `number` | No | Max number of buckets returned. |
| `segmentSize` | `number` | No | Internal candidate size used while collecting top terms. |
| `showTermDocCountError` | `boolean` | No | Include `docCountErrorUpperBound` in output. |
| `minDocCount` | `number` | No | Buckets with fewer docs are excluded. |
| `order` | `object` | No | One-key order object: `{ "count": "desc" }`, `{ "key": "asc" }`, or `{ "<subAggAlias>": "desc" }`. |
| `missing` | `string \| number` | No | Bucket key used when the field is missing. |
| `include` | `string \| string[]` | No | Include regex or explicit value list. |
| `exclude` | `string \| string[]` | No | Exclude regex or explicit value list. |

<Tabs>

<Tab title="TypeScript">
```ts
await index.aggregate({
  aggregations: {
    by_category: {
      $terms: { field: "category", size: 5 },
    },
  },
});
```
</Tab>

<Tab title="Python">
```python
index.aggregate(
    aggregations={
        "by_category": {
            "$terms": {"field": "category", "size": 5}
        }
    }
)
```
</Tab>

<Tab title="Redis CLI">
```bash
SEARCH.AGGREGATE products '{}' '{"by_category": {"$terms": {"field": "category", "size": 5}}}'
```
</Tab>

</Tabs>

### Output

```json
{
  "by_category": {
    "buckets": [
      { "key": "electronics", "docCount": 120 },
      { "key": "books", "docCount": 83 }
    ],
    "sumOtherDocCount": 42
  }
}
```

# $avg
Source: https://upstash.com/docs/redis/search/aggregation-operators/metric-aggregations/avg

`$avg` computes the arithmetic mean of a field across matching documents.

If `missing` is provided, documents without the field are treated as if they had the `missing` value.

### Compatibility

| Field Type | Supported |
|------------|-----------|
| TEXT | No |
| U64/I64/F64 | Yes |
| DATE | Yes |
| BOOL | Yes |
| KEYWORD | No |
| FACET | No |

Field must be `FAST`.

### Arguments

| Argument | Type | Required | Description |
|----------|------|----------|-------------|
| `field` | `string` | Yes | Field to aggregate. |
| `missing` | `number` | No | Fallback value for missing fields. |

<Tabs>

<Tab title="TypeScript">
```ts
await index.aggregate({
  aggregations: {
    avg_price: { $avg: { field: "price", missing: 0 } },
  },
});
```
</Tab>

<Tab title="Python">
```python
index.aggregate(
    aggregations={"avg_price": {"$avg": {"field": "price", "missing": 0}}}
)
```
</Tab>

<Tab title="Redis CLI">
```bash
SEARCH.AGGREGATE products '{}' '{"avg_price": {"$avg": {"field": "price", "missing": 0}}}'
```
</Tab>

</Tabs>

### Output

```json
{ "avg_price": { "value": 40 } }
```

`value` is `null` when no values are available after filtering.

# $cardinality
Source: https://upstash.com/docs/redis/search/aggregation-operators/metric-aggregations/cardinality

`$cardinality` returns the number of distinct values in a field.

All matching field values are deduplicated, then counted.

If `missing` is provided, documents without the field are treated as that fallback key
(which can increase the distinct count by at most one extra value).

### Compatibility

| Field Type | Supported |
|------------|-----------|
| TEXT | No |
| U64/I64/F64 | Yes |
| DATE | Yes |
| BOOL | Yes |
| KEYWORD | Yes |
| FACET | No |

Field must be `FAST`.

### Arguments

| Argument | Type | Required | Description |
|----------|------|----------|-------------|
| `field` | `string` | Yes | Field to aggregate. |
| `missing` | `string \| number` | No | Fallback key for missing fields. |

<Tabs>

<Tab title="TypeScript">
```ts
await index.aggregate({
  aggregations: {
    unique_users: { $cardinality: { field: "userId" } },
  },
});
```
</Tab>

<Tab title="Python">
```python
index.aggregate(
    aggregations={"unique_users": {"$cardinality": {"field": "userId"}}}
)
```
</Tab>

<Tab title="Redis CLI">
```bash
SEARCH.AGGREGATE events '{}' '{"unique_users": {"$cardinality": {"field": "userId"}}}'
```
</Tab>

</Tabs>

### Output

```json
{ "unique_categories": { "value": 3 } }
```

# $count
Source: https://upstash.com/docs/redis/search/aggregation-operators/metric-aggregations/count

`$count` returns how many documents contribute a value for a field.

### How It Works

* By default, only documents that have the field are counted.
* If `missing` is set, documents without the field also contribute to result.

### Compatibility

| Field Type | Supported |
|------------|-----------|
| TEXT | No |
| U64/I64/F64 | Yes |
| DATE | Yes |
| BOOL | Yes |
| KEYWORD | Yes |
| FACET | No |

Field must be `FAST`.

### Arguments

| Argument | Type | Required | Description |
|----------|------|----------|-------------|
| `field` | `string` | Yes | Field to count values for. |
| `missing` | `number` | No | Fallback value for missing fields. |

<Tabs>

<Tab title="TypeScript">
```ts
await index.aggregate({
  aggregations: {
    price_count: { $count: { field: "price" } },
  },
});
```
</Tab>

<Tab title="Python">
```python
index.aggregate(
    aggregations={"price_count": {"$count": {"field": "price"}}}
)
```
</Tab>

<Tab title="Redis CLI">
```bash
SEARCH.AGGREGATE products '{}' '{"price_count": {"$count": {"field": "price"}}}'
```
</Tab>

</Tabs>

### Output

```json
{ "price_count": { "value": 9 } }
```

# $extendedStats
Source: https://upstash.com/docs/redis/search/aggregation-operators/metric-aggregations/extended-stats

`$extendedStats` returns `$stats` plus additional distribution metrics.

In addition to `count`, `sum`, `min`, `max`, and `avg`, this operator provides:

* `sumOfSquares`
* `variance`, `variancePopulation`, `varianceSampling`
* `stdDeviation`, `stdDeviationPopulation`, `stdDeviationSampling`
* `stdDeviationBounds` (`upper`, `lower`, plus sampling/population variants)

`sigma` controls the width of `stdDeviationBounds`.

### Compatibility

| Field Type | Supported |
|------------|-----------|
| TEXT | No |
| U64/I64/F64 | Yes |
| DATE | Yes |
| BOOL | No |
| KEYWORD | No |
| FACET | No |

Field must be `FAST`.

### Arguments

<Tabs>

<Tab title="TypeScript">
```ts
await index.aggregate({
  aggregations: {
    price_extended: {
      $extendedStats: { field: "price", sigma: 2, missing: 0 },
    },
  },
});
```
</Tab>

<Tab title="Python">
```python
index.aggregate(
    aggregations={
        "price_extended": {
            "$extendedStats": {"field": "price", "sigma": 2, "missing": 0}
        }
    }
)
```
</Tab>

<Tab title="Redis CLI">
```bash
SEARCH.AGGREGATE products '{}' '{"price_extended": {"$extendedStats": {"field": "price", "sigma": 2, "missing": 0}}}'
```
</Tab>

</Tabs>

### Output

Returns a single object containing all basic and extended fields. Example shape:

```json
{ "price_extended": {
    "count": 9, "min": 0, "max": 80, "avg": 40, "sum": 360,
    "sumOfSquares": 18000, "variance": 200, "stdDeviation": 14.14,
    "stdDeviationBounds": { "upper": 68.28, "lower": 11.72 }
  }
}
```

# $max
Source: https://upstash.com/docs/redis/search/aggregation-operators/metric-aggregations/max

`$max` returns the maximum field value across matching documents.

If `missing` is set, missing fields are treated as that value.

### Compatibility

| Field Type | Supported |
|------------|-----------|
| TEXT | No |
| U64/I64/F64 | Yes |
| DATE | Yes |
| BOOL | Yes |
| KEYWORD | No |
| FACET | No |

Field must be `FAST`.

### Arguments

<Tabs>

<Tab title="TypeScript">
```ts
await index.aggregate({
  aggregations: {
    most_expensive: { $max: { field: "price", missing: 0 } },
  },
});
```
</Tab>

<Tab title="Python">
```python
index.aggregate(
    aggregations={"most_expensive": {"$max": {"field": "price", "missing": 0}}}
)
```
</Tab>

<Tab title="Redis CLI">
```bash
SEARCH.AGGREGATE products '{}' '{"most_expensive": {"$max": {"field": "price", "missing": 0}}}'
```
</Tab>

</Tabs>

### Output

```json
{ "most_expensive": { "value": 80 } }
```

`value` can be `null` when no values are available.

# $min
Source: https://upstash.com/docs/redis/search/aggregation-operators/metric-aggregations/min

`$min` returns the minimum field value across matching documents.

If `missing` is set, missing fields are treated as that value.

### Compatibility

| Field Type | Supported |
|------------|-----------|
| TEXT | No |
| U64/I64/F64 | Yes |
| DATE | Yes |
| BOOL | Yes |
| KEYWORD | No |
| FACET | No |

Field must be `FAST`.

### Arguments

<Tabs>

<Tab title="TypeScript">
```ts
await index.aggregate({
  aggregations: {
    cheapest: { $min: { field: "price", missing: 0 } },
  },
});
```
</Tab>

<Tab title="Python">
```python
index.aggregate(
    aggregations={"cheapest": {"$min": {"field": "price", "missing": 0}}}
)
```
</Tab>

<Tab title="Redis CLI">
```bash
SEARCH.AGGREGATE products '{}' '{"cheapest": {"$min": {"field": "price", "missing": 0}}}'
```
</Tab>

</Tabs>

### Output

```json
{ "cheapest": { "value": 0 } }
```

`value` can be `null` when no values are available.

# Overview
Source: https://upstash.com/docs/redis/search/aggregation-operators/metric-aggregations/overview

Metric aggregations compute summary numbers over all documents that matched your `filter`.

Use metrics when you want one value (or stats object), not grouped buckets.

### Available Operators

| Operator | What it computes |
|----------|------------------|
| [`$avg`](./avg) | Arithmetic mean |
| [`$sum`](./sum) | Total of values |
| [`$min`](./min) | Smallest value |
| [`$max`](./max) | Largest value |
| [`$count`](./count) | Count of values |
| [`$cardinality`](./cardinality) | Count of distinct values |
| [`$stats`](./stats) | `count`, `sum`, `min`, `max`, `avg` |
| [`$extendedStats`](./extended-stats) | `$stats` + variance and std deviation metrics |
| [`$percentiles`](./percentiles) | Distribution percent points |

### Input Format

Every metric operator takes an object with at least a `field` property:

```json
{"alias_name": {"$avg": {"field": "price"}}}
{"alias_name": {"$avg": {"field": "price", "missing": 0}}}
```

The `field` value must be a string pointing to a FAST field in your schema.

### Behavior Notes

* Metric operators require a `field`.
* The field must be `FAST` in your schema.
* Metric operators do not support nested `$aggs`.
* For many metric operators, `missing` lets you provide a fallback value for documents where the field does not exist.

# $percentiles
Source: https://upstash.com/docs/redis/search/aggregation-operators/metric-aggregations/percentiles

`$percentiles` returns percentile cut points for a field.

A percentile tells you the value below which a percentage of observations fall.

* `50`th percentile: median-like center point
* `95`th percentile: tail latency/price threshold
* `99`th percentile: extreme tail threshold

### Compatibility

| Field Type | Supported |
|------------|-----------|
| TEXT | No |
| U64/I64/F64 | Yes |
| DATE | Yes |
| BOOL | No |
| KEYWORD | No |
| FACET | No |

Field must be `FAST`.

### Arguments

| Argument | Type | Required | Description |
|----------|------|----------|-------------|
| `field` | `string` | Yes | Field to aggregate. |
| `percents` | `number[]` | No | Percent points to calculate (for example `[50, 95, 99]`). |
| `keyed` | `boolean` | No | If `true` (default), returns a map. If `false`, returns an array of `{ key, value }`. |
| `missing` | `number` | No | Fallback value for missing fields. |

If `percents` is omitted, defaults to `[1.0, 5.0, 25.0, 50.0, 75.0, 95.0, 99.0]`.

<Tabs>

<Tab title="TypeScript">
```ts
await index.aggregate({
  aggregations: {
    latency_pct: {
      $percentiles: { field: "latencyMs", percents: [50, 95, 99], keyed: true },
    },
  },
});
```
</Tab>

<Tab title="Python">
```python
index.aggregate(
    aggregations={
        "latency_pct": {
            "$percentiles": {
                "field": "latencyMs",
                "percents": [50, 95, 99],
                "keyed": True,
            }
        }
    }
)
```
</Tab>

<Tab title="Redis CLI">
```bash
SEARCH.AGGREGATE logs '{}' '{"latency_pct": {"$percentiles": {"field": "latencyMs", "percents": [50, 95, 99], "keyed": true}}}'
```
</Tab>

</Tabs>

### Output

`keyed: true` (default):

```json
{
  "values": {
    "50.0": 40,
    "95.0": 76,
    "99.0": 79.2
  }
}
```

`keyed: false`:

```json
{
  "values": [
    { "key": 50, "value": 40 },
    { "key": 95, "value": 76 },
    { "key": 99, "value": 79.2 }
  ]
}
```

# $stats
Source: https://upstash.com/docs/redis/search/aggregation-operators/metric-aggregations/stats

`$stats` returns multiple basic metrics in one pass.

For the selected field, it computes:

* `count`
* `sum`
* `min`
* `max`
* `avg`

This is equivalent to running `$count`, `$sum`, `$min`, `$max`, and `$avg` together, but returned as a single object.

### Compatibility

| Field Type | Supported |
|------------|-----------|
| TEXT | No |
| U64/I64/F64 | Yes |
| DATE | Yes |
| BOOL | Yes |
| KEYWORD | No |
| FACET | No |

Field must be `FAST`.

### Arguments

<Tabs>

<Tab title="TypeScript">
```ts
await index.aggregate({
  aggregations: {
    price_stats: { $stats: { field: "price", missing: 0 } },
  },
});
```
</Tab>

<Tab title="Python">
```python
index.aggregate(
    aggregations={"price_stats": {"$stats": {"field": "price", "missing": 0}}}
)
```
</Tab>

<Tab title="Redis CLI">
```bash
SEARCH.AGGREGATE products '{}' '{"price_stats": {"$stats": {"field": "price", "missing": 0}}}'
```
</Tab>

</Tabs>

### Output

```json
{ "price_stats": { "count": 9, "min": 0, "max": 80, "sum": 360, "avg": 40 } }
```

`min`, `max`, and `avg` can be `null` when no values are available.

# $sum
Source: https://upstash.com/docs/redis/search/aggregation-operators/metric-aggregations/sum

`$sum` computes the total of a field across matching documents.

If `missing` is set, missing fields contribute that fallback value.

### Compatibility

| Field Type | Supported |
|------------|-----------|
| TEXT | No |
| U64/I64/F64 | Yes |
| DATE | Yes |
| BOOL | Yes |
| KEYWORD | No |
| FACET | No |

Field must be `FAST`.

### Arguments

<Tabs>

<Tab title="TypeScript">
```ts
await index.aggregate({
  aggregations: {
    total_price: { $sum: { field: "price", missing: 0 } },
  },
});
```
</Tab>

<Tab title="Python">
```python
index.aggregate(
    aggregations={"total_price": {"$sum": {"field": "price", "missing": 0}}}
)
```
</Tab>

<Tab title="Redis CLI">
```bash
SEARCH.AGGREGATE products '{}' '{"total_price": {"$sum": {"field": "price", "missing": 0}}}'
```
</Tab>

</Tabs>

### Output

```json
{ "total_price": { "value": 360 } }
```

`value` can be `null` when no values are available.

# Aggregations
Source: https://upstash.com/docs/redis/search/aggregations

Aggregations let you compute analytics over your indexed data — metrics like averages, sums, and statistics,
as well as bucket-based groupings like terms, ranges, and histograms.

They are useful when you want to answer questions like:

* "What is the average price?"
* "How many unique users do we have?"
* "How many orders fall into each price range?"
* "How does traffic change per hour/day?"

<Tabs>

<Tab title="TypeScript">
```ts
const result = await index.aggregate({
  aggregations: {
    avg_price: { $avg: { field: "price" } },
  },
});
```
</Tab>

<Tab title="Python">
```python
result = index.aggregate(
    aggregations={"avg_price": {"$avg": {"field": "price"}}},
)
```
</Tab>

<Tab title="Redis CLI">
```bash
SEARCH.AGGREGATE products '{}' '{"avg_price": {"$avg": {"field": "price"}}}'
```
</Tab>

</Tabs>

Aggregation requests have two phases:

1. **Document selection**: Optional `filter` selects which documents participate.
2. **Aggregation computation**: the selected set is reduced into metric values and/or buckets.

Each aggregation is defined with an **alias** (the key you choose for the result) and an **operator** that specifies what to compute.

### Response Format

<Tabs>

<Tab title="TypeScript">
```ts
const result = await index.aggregate({
  aggregations: {
    avg_price: { $avg: { field: "price" } },
    by_category: { $terms: { field: "category", size: 5 } },
  },
});

// result is an object keyed by alias:
// {
//   avg_price: { value: 49.99 },
//   by_category: {
//     buckets: [
//       { key: "electronics", docCount: 42 },
//       { key: "clothing", docCount: 31 },
//     ],
//   },
// }
```
</Tab>

<Tab title="Python">
```python
result = index.aggregate(
    aggregations={
        "avg_price": {"$avg": {"field": "price"}},
        "by_category": {"$terms": {"field": "category", "size": 5}},
    },
)

# result is a dict keyed by alias:
# {
#   "avg_price": {"value": 49.99},
#   "by_category": {
#     "buckets": [
#       {"key": "electronics", "docCount": 42},
#       {"key": "clothing", "docCount": 31},
#     ],
#   },
# }
```
</Tab>

<Tab title="Redis CLI">
```bash
SEARCH.AGGREGATE products '{}' '{"avg_price": {"$avg": {"field": "price"}}, "by_category": {"$terms": {"field": "category", "size": 5}}}'

# Response (`redis-cli --json`) is an object keyed by alias:
# {"avg_price":{"value":49.99},"by_category":{"buckets":[{"key":"electronics","docCount":42},{"key":"clothing","docCount":31}]}}
```
</Tab>

</Tabs>

## Filtering

Use `filter` to restrict which documents participate in the aggregation.

Filtering uses the same query syntax as [queries](./querying).

<Tabs>

<Tab title="TypeScript">
```ts
const result = await index.aggregate({
  filter: { inStock: true },
  aggregations: {
    avg_price: { $avg: { field: "price" } },
  },
});
```
</Tab>

<Tab title="Python">
```python
result = index.aggregate(
    filter={"inStock": True},
    aggregations={
        "avg_price": {"$avg": {"field": "price"}},
    },
)
```
</Tab>

<Tab title="Redis CLI">
```bash
SEARCH.AGGREGATE products '{"inStock": true}' '{"avg_price": {"$avg": {"field": "price"}}}'
```
</Tab>

</Tabs>

## Multiple Aggregations in One Request

You can compute multiple top-level aggregations in one call by defining multiple aliases under `aggregations`.

Each alias is computed against the same filtered document set.

<Tabs>

<Tab title="TypeScript">
```ts
const result = await index.aggregate({
  aggregations: {
    avg_price: { $avg: { field: "price" } },
    price_stats: { $stats: { field: "price" } },
    by_category: { $terms: { field: "category", size: 5 } },
    price_ranges: {
      $range: {
        field: "price",
        ranges: [{ to: 50 }, { from: 50 }],
      },
    },
  },
});
```
</Tab>

<Tab title="Python">
```python
result = index.aggregate(
    aggregations={
        "avg_price": {"$avg": {"field": "price"}},
        "price_stats": {"$stats": {"field": "price"}},
        "by_category": {"$terms": {"field": "category", "size": 5}},
        "price_ranges": {
            "$range": {
                "field": "price",
                "ranges": [{"to": 50}, {"from": 50}],
            }
        },
    },
)
```
</Tab>

<Tab title="Redis CLI">
```bash
SEARCH.AGGREGATE products '{}' '{"avg_price": {"$avg": {"field": "price"}}, "price_stats": {"$stats": {"field": "price"}}, "by_category": {"$terms": {"field": "category", "size": 5}}, "price_ranges": {"$range": {"field": "price", "ranges": [{"to": 50}, {"from": 50}]}}}'
```
</Tab>

</Tabs>

## Nested Aggregations

Bucket operators can include sub-aggregations via `$aggs`, so you can compute per-bucket metrics.

* `$terms`, `$range`, `$histogram`, and `$dateHistogram` support nested `$aggs`.
* `$facet` does not support nested `$aggs`.
* Metric operators do not support nested `$aggs`.

<Tabs>

<Tab title="TypeScript">
```ts
const result = await index.aggregate({
  aggregations: {
    by_category: {
      $terms: { field: "category" },
      $aggs: {
        avg_price: { $avg: { field: "price" } },
        min_price: { $min: { field: "price" } },
      },
    },
  },
});
```
</Tab>

<Tab title="Python">
```python
result = index.aggregate(
    aggregations={
        "by_category": {
            "$terms": {"field": "category"},
            "$aggs": {
                "avg_price": {"$avg": {"field": "price"}},
                "min_price": {"$min": {"field": "price"}},
            },
        },
    },
)
```
</Tab>

<Tab title="Redis CLI">
```bash
SEARCH.AGGREGATE products '{}' '{"by_category": {"$terms": {"field": "category"}, "$aggs": {"avg_price": {"$avg": {"field": "price"}}, "min_price": {"$min": {"field": "price"}}}}}'
```
</Tab>

</Tabs>

## Operator Families

### Metric Aggregations

Metric aggregations return numeric summaries.

| Operator | Typical use |
|----------|-------------|
| [`$avg`](./aggregation-operators/metric-aggregations/avg) | Mean value |
| [`$sum`](./aggregation-operators/metric-aggregations/sum) | Total |
| [`$min`](./aggregation-operators/metric-aggregations/min) | Smallest value |
| [`$max`](./aggregation-operators/metric-aggregations/max) | Largest value |
| [`$count`](./aggregation-operators/metric-aggregations/count) | Number of values |
| [`$cardinality`](./aggregation-operators/metric-aggregations/cardinality) | Number of distinct values |
| [`$stats`](./aggregation-operators/metric-aggregations/stats) | Basic summary stats |
| [`$extendedStats`](./aggregation-operators/metric-aggregations/extended-stats) | Stats + variance/std deviation |
| [`$percentiles`](./aggregation-operators/metric-aggregations/percentiles) | Distribution cut points |

See the [metric overview](./aggregation-operators/metric-aggregations/overview).

### Bucket Aggregations

Bucket aggregations partition documents into groups.

| Operator | Typical use |
|----------|-------------|
| [`$terms`](./aggregation-operators/bucket-aggregations/terms) | Top values by field |
| [`$range`](./aggregation-operators/bucket-aggregations/range) | Custom ranges |
| [`$histogram`](./aggregation-operators/bucket-aggregations/histogram) | Fixed numeric bins |
| [`$dateHistogram`](./aggregation-operators/bucket-aggregations/date-histogram) | Fixed time bins |
| [`$facet`](./aggregation-operators/bucket-aggregations/facet) | Hierarchical facets |

See the [bucket overview](./aggregation-operators/bucket-aggregations/overview).

# Aliases
Source: https://upstash.com/docs/redis/search/aliases

Aliases let you create alternative names for your search indices. This is useful for zero-downtime reindexing — you can build a new index, then atomically swap the alias to point to it.

***

### Adding an Alias

The `SEARCH.ALIASADD` command creates a new alias or updates an existing alias to point to a different index.

Returns `1` if a new alias was created, or `2` if an existing alias was updated to point to a new index.

<Tabs>

<Tab title="TypeScript">
```ts
// Top-level: create or update an alias
const result = await redis.search.alias.add({
  indexName: "products-v2",
  alias: "products",
});

// Via index method
const result2 = await index.addAlias({ alias: "products" });
```
</Tab>

<Tab title="Python">
```python
# Top-level: create or update an alias
result = redis.search.alias.add(index_name="products-v2", alias="products")

# Via index method
result = index.add_alias(alias="products")
```
</Tab>

<Tab title="Redis CLI">
```bash
# Create or update an alias
SEARCH.ALIASADD products products-v2
```
</Tab>

</Tabs>

A common pattern is to use aliases for zero-downtime reindexing:

<Tabs>

<Tab title="TypeScript">
```ts
// 1. Create a new index with updated schema
const productsV2 = await redis.search.createIndex({
  name: "products-v2",
  dataType: "json",
  prefix: "product:",
  schema,
});

// 2. Wait for indexing to complete
await productsV2.waitIndexing();

// 3. Swap the alias to point to the new index
await redis.search.alias.add({
  indexName: "products-v2",
  alias: "products",
});

// 4. Drop the old index
const oldIndex = redis.search.index({ name: "products-v1" });
await oldIndex.drop();
```
</Tab>

<Tab title="Python">
```python
# 1. Create a new index with updated schema
products_v2 = redis.search.create_index(
    name="products-v2",
    data_type="json",
    prefix="product:",
    schema=schema,
)

# 2. Wait for indexing to complete
products_v2.wait_indexing()

# 3. Swap the alias to point to the new index
redis.search.alias.add(index_name="products-v2", alias="products")

# 4. Drop the old index
old_index = redis.search.index(name="products-v1")
old_index.drop()
```
</Tab>

<Tab title="Redis CLI">
```bash
# 1. Create new index
SEARCH.CREATE products-v2 ON JSON PREFIX 1 product: SCHEMA name TEXT price F64 FAST

# 2. Wait for indexing
SEARCH.WAITINDEXING products-v2

# 3. Swap alias
SEARCH.ALIASADD products products-v2

# 4. Drop old index
SEARCH.DROP products-v1
```
</Tab>

</Tabs>

***

### Deleting an Alias

The `SEARCH.ALIASDEL` command removes an alias.

Returns `1` if the alias was deleted, or `0` if the alias was not found.

<Tabs>

<Tab title="TypeScript">
```ts
const result = await redis.search.alias.delete({ alias: "products" });
```
</Tab>

<Tab title="Python">
```python
result = redis.search.alias.delete(alias="products")
```
</Tab>

<Tab title="Redis CLI">
```bash
SEARCH.ALIASDEL products
```
</Tab>

</Tabs>

***

### Listing Aliases

The `SEARCH.LISTALIASES` command returns all aliases and the indices they point to.

<Tabs>

<Tab title="TypeScript">
```ts
const aliases = await redis.search.alias.list();
// → { "products": "products-v2", "users": "users-v1" }
```
</Tab>

<Tab title="Python">
```python
aliases = redis.search.alias.list()
# → {"products": "products-v2", "users": "users-v1"}
```
</Tab>

<Tab title="Redis CLI">
```bash
SEARCH.LISTALIASES
# → [["products", "products-v2"], ["users", "users-v1"]]
```
</Tab>

</Tabs>

# Command Reference
Source: https://upstash.com/docs/redis/search/command-reference

A complete reference of all Upstash Redis Search commands, their syntax, and return values.

<Note>
Upstash Redis Search uses `SEARCH.*` commands. These are **not** the same as the `FT.*` commands
from the open-source RediSearch module. The two are completely separate implementations and are
not compatible with each other.
</Note>

## Index Commands

### SEARCH.CREATE

Creates a new search index.

```bash
SEARCH.CREATE <name> ON <JSON|HASH|STRING>
  PREFIX <count> <prefix> [<prefix> ...]
  [LANGUAGE <language>]
  [SKIPINITIALSCAN]
  [EXISTSOK]
  SCHEMA <field> <type> [FAST] [NOSTEM] [NOTOKENIZE] [FROM <source_field>] ...
```

**Returns:** `1` on success. With `EXISTSOK`, returns `0` if an identical index already exists. Returns an error if the existing index has a different configuration.

<Tabs>
<Tab title="Redis CLI">
```bash
SEARCH.CREATE products ON JSON PREFIX 1 product: SCHEMA name TEXT price F64 FAST inStock BOOL
```
</Tab>
<Tab title="curl">
```bash
curl -X POST https://YOUR_ENDPOINT.upstash.io \
  -H "Authorization: Bearer $UPSTASH_REDIS_REST_TOKEN" \
  -d '["SEARCH.CREATE", "products", "ON", "JSON", "PREFIX", "1", "product:", "SCHEMA", "name", "TEXT", "price", "F64", "FAST", "inStock", "BOOL"]'
```
</Tab>
</Tabs>

***

### SEARCH.DROP

Removes an index. The underlying Redis keys are **not** deleted.

```bash
SEARCH.DROP <name>
```

**Returns:** `1` if dropped, `0` if the index was not found.

***

### SEARCH.DESCRIBE

Returns metadata about an index.

```bash
SEARCH.DESCRIBE <name>
```

**Returns:** Index metadata including name, data type, prefixes, language, and schema definition. Returns `null` if the index does not exist.

***

### SEARCH.WAITINDEXING

Blocks until all pending index updates are processed and visible to queries.

```bash
SEARCH.WAITINDEXING <name>
```

**Returns:** `1` when indexing is complete, `0` if the index was not found.

<Warning>
Do not call `SEARCH.WAITINDEXING` after every write. Batch updates are necessary for
optimal indexing performance. Use this command only when you need to ensure queries
reflect recent changes, such as in tests or CI pipelines.
</Warning>

***

## Query Commands

### SEARCH.QUERY

Searches for documents matching a JSON filter.

```bash
SEARCH.QUERY <name> '<json_filter>'
  [LIMIT <count>]
  [OFFSET <offset>]
  [ORDERBY <field> <ASC|DESC>]
  [SELECT <count> <field> [<field> ...]]
  [NOCONTENT]
  [HIGHLIGHT FIELDS <count> <field> [<field> ...] [TAGS <open> <close>]]
  [SCOREFUNC ...]
```

**Parameters:**

| Parameter | Description | Default |
|-----------|-------------|---------|
| `LIMIT` | Maximum number of results to return. Must be between 1 and 1000. | 10 |
| `OFFSET` | Number of results to skip (for pagination). | 0 |
| `ORDERBY` | Sort by a FAST field in `ASC` or `DESC` order. | Sort by relevance score (descending) |
| `SELECT` | Return only specific fields. Prefix with count of fields. | All fields |
| `NOCONTENT` | Return only keys and scores, no document content. | Disabled |
| `HIGHLIGHT` | Wrap matching terms in tags. Default tags: `<em>` / `</em>`. | Disabled |
| `SCOREFUNC` | Adjust relevance scores using numeric field values. | Disabled |

**Response format (Redis CLI):**

```
[
  ["key1", "score1", [["$", "{\"name\": \"...\", ...}"]]],
  ["key2", "score2", [["$", "{\"name\": \"...\", ...}"]]]
]
```

Each result is an array of `[key, score, content]` where:
* `key` — the Redis key of the matching document
* `score` — relevance score (float)
* `content` — array of field-value pairs (for JSON indexes: `[["$", "<json_string>"]]`; for HASH indexes: `[["field", "value"], ...]`)

When `NOCONTENT` is used, the content element is omitted.
When `SELECT` is used, only the selected fields appear in the content.

<Tabs>
<Tab title="Redis CLI">
```bash
SEARCH.QUERY products '{"name": "wireless"}' LIMIT 10 OFFSET 0
```
</Tab>
<Tab title="curl">
```bash
curl -X POST https://YOUR_ENDPOINT.upstash.io \
  -H "Authorization: Bearer $UPSTASH_REDIS_REST_TOKEN" \
  -d '["SEARCH.QUERY", "products", "{\"name\": \"wireless\"}", "LIMIT", "10", "OFFSET", "0"]'
```
</Tab>
</Tabs>

***

### SEARCH.COUNT

Returns the number of documents matching a query without retrieving them.

```bash
SEARCH.COUNT <name> '<json_filter>'
```

**Returns:** An integer — the count of matching documents.

<Tabs>
<Tab title="Redis CLI">
```bash
SEARCH.COUNT products '{"inStock": true}'
```
</Tab>
<Tab title="curl">
```bash
curl -X POST https://YOUR_ENDPOINT.upstash.io \
  -H "Authorization: Bearer $UPSTASH_REDIS_REST_TOKEN" \
  -d '["SEARCH.COUNT", "products", "{\"inStock\": true}"]'
```
</Tab>
</Tabs>

***

### SEARCH.AGGREGATE

Computes analytics (metrics and buckets) over matching documents.

```bash
SEARCH.AGGREGATE <name> '<json_filter>' '<json_aggregations>'
```

**Response format (Redis CLI):**

In `redis-cli --json`, the response is an object keyed by alias:

```json
{
  "avg_price": { "value": 49.99 },
  "by_category": { "buckets": [{ "key": "electronics", "docCount": 42 }] }
}
```

Raw RESP output may be rendered differently by client/protocol settings, but semantically each top-level alias maps to its aggregation result.

<Tabs>
<Tab title="Redis CLI">
```bash
SEARCH.AGGREGATE products '{}' '{"avg_price": {"$avg": {"field": "price"}}}'
```
</Tab>
<Tab title="curl">
```bash
curl -X POST https://YOUR_ENDPOINT.upstash.io \
  -H "Authorization: Bearer $UPSTASH_REDIS_REST_TOKEN" \
  -d '["SEARCH.AGGREGATE", "products", "{}", "{\"avg_price\": {\"$avg\": {\"field\": \"price\"}}}"]'
```
</Tab>
</Tabs>

***

## Alias Commands

### SEARCH.ALIASADD

Creates or updates an alias pointing to an index.

```bash
SEARCH.ALIASADD <alias> <index_name>
```

**Returns:** `1` if a new alias was created, `2` if an existing alias was updated.

***

### SEARCH.ALIASDEL

Removes an alias.

```bash
SEARCH.ALIASDEL <alias>
```

**Returns:** `1` if deleted, `0` if the alias was not found.

***

### SEARCH.LISTALIASES

Returns all aliases and the indices they point to.

```bash
SEARCH.LISTALIASES
```

**Returns:** An array of `[alias, index_name]` pairs.

***

## REST API Usage

All search commands can be sent via the Upstash REST API using a JSON array POST body.
Each element of the array corresponds to a token in the command.

```bash
curl -X POST https://YOUR_ENDPOINT.upstash.io \
  -H "Authorization: Bearer $UPSTASH_REDIS_REST_TOKEN" \
  -d '["COMMAND", "arg1", "arg2", ...]'
```

The JSON filter and aggregation arguments are passed as string values within the array (not as nested JSON objects):

```bash
# Correct — filter is a string inside the array
["SEARCH.QUERY", "products", "{\"name\": \"wireless\"}", "LIMIT", "10"]

# Incorrect — filter is a nested object
["SEARCH.QUERY", "products", {"name": "wireless"}, "LIMIT", "10"]
```

Search commands also work through the `/pipeline` endpoint for batching multiple commands in a single HTTP request.

# Counting
Source: https://upstash.com/docs/redis/search/counting

The `SEARCH.COUNT` command returns the number of documents matching a query without retrieving them.

You can use `SEARCH.COUNT` for analytics, pagination UI (showing "X results found"),
or validating queries before retrieving results.

<Tabs>

<Tab title="TypeScript">
```ts
// Count all electronics
await products.count({
  filter: {
    category: "electronics",
  },
});

// Count in-stock items under $100
await products.count({
  filter: {
    inStock: true,
    price: { $lt: 100 },
  },
});
```
</Tab>

<Tab title="Python">
```python
# Count all electronics
products.count(filter={"category": "electronics"})

# Count in-stock items under $100
products.count(filter={"inStock": True, "price": {"$lt": 100}})
```
</Tab>

<Tab title="Redis CLI">
```bash
# Count all electronics
SEARCH.COUNT products '{"category": "electronics"}'

# Count in-stock items under $100
SEARCH.COUNT products '{"inStock": true, "price": {"$lt": 100}}'
```
</Tab>

</Tabs>

# Document Updates
Source: https://upstash.com/docs/redis/search/document-updates

Documents in a search index are regular Redis keys.

When a key matches an index prefix, it is indexed automatically. When the key changes, the index is updated automatically.

<Note>
There is no separate update command for search. Use regular Redis write commands to change your data.
</Note>

Any command that modifies a matching key updates the index. For example, this includes commands such as:

* JSON commands such as `JSON.SET`, `JSON.MERGE`, ...
* Hash commands such as `HSET`, `HINCRBY`, ...
* String commands such as `SET`, `SETEX`, ...
* Generic commands such as `DEL`, `EXPIRE`, `PEXPIRE`, ...

This is not an exhaustive list. The rule is that if the command changes a key tracked by the index, the index is updated.

Index updates are batched for performance, so recent writes may not immediately appear in search results.
Use [`SEARCH.WAITINDEXING`](/docs/redis/search/index-management#waiting-for-indexing) when you need to ensure queries reflect recent changes.

## JSON Documents

For JSON indexes, any JSON command that modifies a matching key updates the indexed document.

<Tabs>

<Tab title="TypeScript">
```ts
import { Redis } from "@upstash/redis";

const redis = Redis.fromEnv();
const products = redis.search.index({ name: "products" });

await redis.json.set("product:1", "$.price", 79.99);

await products.waitIndexing();

const discounted = await products.query({
  filter: { price: { $lt: 90 } },
});
```
</Tab>

<Tab title="Python">
```python
from upstash_redis import Redis

redis = Redis.from_env()
products = redis.search.index(name="products")

redis.json.set("product:1", "$.price", 79.99)

products.wait_indexing()

discounted = products.query(filter={"price": {"$lt": 90}})
```
</Tab>

<Tab title="Redis CLI">
```bash
JSON.SET product:1 $.price 79.99

SEARCH.WAITINDEXING products
SEARCH.QUERY products '{"price":{"$lt":90}}'
```
</Tab>

</Tabs>

## Hash Documents

For hash indexes, any hash command that modifies a matching key updates the indexed document.

<Tabs>

<Tab title="TypeScript">
```ts
const articles = redis.search.index({ name: "articles" });

await redis.hset("article:1", {
  status: "published",
  views: 125,
});

await articles.waitIndexing();

const published = await articles.query({
  filter: { status: "published" },
});
```
</Tab>

<Tab title="Python">
```python
articles = redis.search.index(name="articles")

redis.hset("article:1", values={
    "status": "published",
    "views": 125,
})

articles.wait_indexing()

published = articles.query(filter={"status": "published"})
```
</Tab>

<Tab title="Redis CLI">
```bash
HSET article:1 status published views 125

SEARCH.WAITINDEXING articles
SEARCH.QUERY articles '{"status":"published"}'
```
</Tab>

</Tabs>

## String Documents

For string indexes, indexed keys must contain valid JSON strings.
Any command that replaces or modifies the matching string key updates the indexed document.

<Tabs>

<Tab title="TypeScript">
```ts
const notes = redis.search.index({ name: "notes" });

await redis.set("note:1", {
  title: "Release checklist",
  status: "done",
});

await notes.waitIndexing();

const done = await notes.query({
  filter: { status: "done" },
});
```
</Tab>

<Tab title="Python">
```python
notes = redis.search.index(name="notes")

redis.set("note:1", '{"title":"Release checklist","status":"done"}')

notes.wait_indexing()

done = notes.query(filter={"status": "done"})
```
</Tab>

<Tab title="Redis CLI">
```bash
SET note:1 '{"title":"Release checklist","status":"done"}'

SEARCH.WAITINDEXING notes
SEARCH.QUERY notes '{"status":"done"}'
```
</Tab>

</Tabs>

## Deletes

Deleting a matching key removes the document from the index.

<Tabs>

<Tab title="TypeScript">
```ts
await redis.del("product:1");
await products.waitIndexing();
```
</Tab>

<Tab title="Python">
```python
redis.delete("product:1")
products.wait_indexing()
```
</Tab>

<Tab title="Redis CLI">
```bash
DEL product:1
SEARCH.WAITINDEXING products
```
</Tab>

</Tabs>

## Expiration

When a matching key expires, Upstash Redis Search removes the expired document from the index.

<Tabs>

<Tab title="TypeScript">
```ts
await redis.expire("product:flash-sale", 3600);
```
</Tab>

<Tab title="Python">
```python
redis.expire("product:flash-sale", 3600)
```
</Tab>

<Tab title="Redis CLI">
```bash
EXPIRE product:flash-sale 3600
```
</Tab>

</Tabs>

## Eviction

When an indexed key is evicted, Upstash Redis Search removes the document from the index. Once the Redis key is gone,
it no longer appears in search results.

# Quickstart
Source: https://upstash.com/docs/redis/search/getting-started

## 1. Create Index

<Tabs>

<Tab title="TypeScript">
```ts
import { Redis, s } from "@upstash/redis";

const redis = Redis.fromEnv();

const index = await redis.search.createIndex({
  name: "products",
  dataType: "json",
  prefix: "product:",
  schema: s.object({
    name: s.string(),
    description: s.string(),
    category: s.string().noTokenize(),
    price: s.number(),
    inStock: s.boolean(),
  }),
});
```
</Tab>

<Tab title="Python">
```python
from upstash_redis import Redis

redis = Redis.from_env()

index = redis.search.create_index(
    name="products",
    data_type="json",
    prefixes="product:",
    schema={
        "name": "TEXT",
        "description": "TEXT",
        "category": {"type": "TEXT", "notokenize": True},
        "price": "F64",
        "inStock": "BOOL",
    },
)
```
</Tab>

<Tab title="Redis CLI">
```bash
SEARCH.CREATE products ON JSON PREFIX 1 product: SCHEMA name TEXT description TEXT category TEXT NOTOKENIZE price F64 FAST inStock BOOL
```
</Tab>

</Tabs>

<Note>
Create an index once, not on every request. `createIndex` throws if an index with
the same name already exists. To make setup safely re-runnable, pass `exists_ok=True`
in the Python SDK, or wrap the call in a `try/catch` in TypeScript.
</Note>

## 2. Add Data

Add data using standard Redis JSON commands. Any key matching the index prefix will be automatically indexed.

<Note>
Writes are indexed asynchronously: a `JSON.SET` returns before the document is
searchable. For demos and tests, call `waitIndexing()` / `wait_indexing()` to
block until pending updates are applied. In production, queries running on a later
request will normally hit an up-to-date index without waiting.
</Note>

<Tabs>

<Tab title="TypeScript">
```ts
await redis.json.set("product:1", "$", {
  name: "Wireless Headphones",
  description:
    "Premium noise-cancelling wireless headphones with 30-hour battery life",
  category: "electronics",
  price: 199.99,
  inStock: true,
});

await redis.json.set("product:2", "$", {
  name: "Running Shoes",
  description: "Lightweight running shoes with advanced cushioning technology",
  category: "sports",
  price: 129.99,
  inStock: true,
});

await index.waitIndexing();
```
</Tab>

<Tab title="Python">
```python
redis.json.set("product:1", "$", {
    "name": "Wireless Headphones",
    "description": "Premium noise-cancelling wireless headphones with 30-hour battery life",
    "category": "electronics",
    "price": 199.99,
    "inStock": True,
})

redis.json.set("product:2", "$", {
    "name": "Running Shoes",
    "description": "Lightweight running shoes with advanced cushioning technology",
    "category": "sports",
    "price": 129.99,
    "inStock": True,
})

index.wait_indexing()
```
</Tab>

<Tab title="Redis CLI">
```bash
JSON.SET product:1 $ '{"name": "Wireless Headphones", "description": "Premium noise-cancelling wireless headphones with 30-hour battery life", "category": "electronics", "price": 199.99, "inStock": true}'
JSON.SET product:2 $ '{"name": "Running Shoes", "description": "Lightweight running shoes with advanced cushioning technology", "category": "sports", "price": 129.99, "inStock": true}'

SEARCH.WAITINDEXING products
```
</Tab>

</Tabs>

## 3. Search Data

<Tabs>

<Tab title="TypeScript">
```ts
const results = await index.query({
  filter: { description: "wireless" },
});

const count = await index.count({
  filter: { price: { $lt: 150 } },
});
```
</Tab>

<Tab title="Python">
```python
results = index.query(filter={"description": "wireless"})

count = index.count(filter={"price": {"$lt": 150}})
```
</Tab>

<Tab title="Redis CLI">
```bash
SEARCH.QUERY products '{"description": "wireless"}'

SEARCH.COUNT products '{"price": {"$lt": 150}}'
```
</Tab>

</Tabs>

## Next Steps

<CardGroup cols={2}>
  <Card
    title="Schema Definition"
    icon="table-columns"
    href="/redis/search/schema-definition"
  >
    Define the fields you want to index and how they are matched
  </Card>
  <Card
    title="Querying"
    icon="magnifying-glass"
    href="/redis/search/querying"
  >
    Learn the JSON-based query language with filters and operators
  </Card>
  <Card
    title="Aggregations"
    icon="layer-group"
    href="/redis/search/aggregations"
  >
    Group and summarize your indexed data with aggregation pipelines
  </Card>
  <Card
    title="Recipes"
    icon="book-open"
    href="/redis/search/recipes/overview"
  >
    Complete, real-world examples you can adapt to your own use cases
  </Card>
</CardGroup>

# Indices
Source: https://upstash.com/docs/redis/search/index-management

An index is a data structure that enables **fast full-text search and filtering across your Redis data**. Without an index, searching requires scanning every key in your database: an operation that becomes very slow as your data grows.

When you create a search index, Upstash Redis builds an optimized lookup structure for the schema you specify. This allows queries to find matching documents in milliseconds, regardless of dataset size. The index automatically stays in sync with your data: any keys matching the index prefix are indexed when created, updated when modified, and removed from the index when deleted.

You define an index once by specifying:

* A **name** to identify the index
* A **prefix** pattern to determine which keys to track (e.g., `user:`)
* A **schema** describing which fields to index and their types

***

### Creating an Index

An index is identified by its name, which must be a unique key in Redis. Each index works with a single key type (JSON, hash, or string).

<Tabs>

<Tab title="TypeScript">
```ts
import { Redis, s } from "@upstash/redis";

const redis = Redis.fromEnv();

// Basic index on JSON data
const users = await redis.search.createIndex({
  name: "users",
  dataType: "json",
  prefix: "user:",
  schema: s.object({
    name: s.string(),
    email: s.string(),
    age: s.number(),
  }),
});

```
</Tab>

<Tab title="Python">
```python
from upstash_redis import Redis

redis = Redis.from_env()

users = redis.search.create_index(
    name="users",
    data_type="json",
    prefix="user:",
    schema={
        "name": "TEXT",
        "email": "TEXT",
        "age": "U64",
    },
)
```
</Tab>

<Tab title="Redis CLI">
```bash
# Basic index on hash data
SEARCH.CREATE users on JSON PREFIX 1 user: SCHEMA name TEXT email TEXT age u64
```

</Tab>

</Tabs>

**We only create an index once**, for example inside of a script we run once. We do not recommend creating an index at runtime, for example inside of a serverless function.

* For **JSON** indices, an index field can be specified for fields on various nested levels.

* For **hash** indices, an index field can be specified for fields. As hash fields cannot have
  nesting on their own, for this kind of indices, only top-level schema fields can be used.

* For **string** indices, indexed keys must be valid JSON strings. A field on any nesting level
  can be indexed, similar to JSON indices.

<Tabs>

<Tab title="TypeScript">
```ts
import { Redis, s } from "@upstash/redis";
const redis = Redis.fromEnv();

// String index with nested schema fields
const comments = await redis.search.createIndex({
  name: "comments",
  dataType: "string",
  prefix: "comment:",
  schema: s.object({
    user: s.object({
      name: s.string(),
      email: s.string().noTokenize(),
    }),
    comment: s.string(),
    upvotes: s.number(),
    commentedAt: s.date().fast(),
  }),
});

```
</Tab>

<Tab title="Python">
```python
from upstash_redis import Redis

redis = Redis.from_env()

comments = redis.search.create_index(
    name="comments",
    data_type="string",
    prefix="comment:",
    schema={
        "user.name": "TEXT",
        "user.email": {"type": "TEXT", "notokenize": True},
        "comment": "TEXT",
        "upvotes": "U64",
        "commentedAt": {"type": "DATE", "fast": True},
    },
)
```
</Tab>

<Tab title="Redis CLI">
```bash
# String index with nested schema fields
SEARCH.CREATE comments ON STRING PREFIX 1 comment: SCHEMA user.name TEXT user.email TEXT NOTOKENIZE comment TEXT upvotes U64 FAST commentedAt DATE FAST
```

</Tab>

</Tabs>

It is possible to define an index for more than one prefix. However, there are some rules concerning the usage of
multiple prefixes:

* Prefixes must not contain duplicates.
* No prefix should cover another prefix (e.g., `user:` and `user:admin:` are not allowed together).
* Multiple distinct prefixes are allowed (e.g., `article:` and `blog:` are valid together).

<Tabs>

<Tab title="TypeScript">
```ts {4}
const articles = await redis.search.createIndex({
  name: "articles",
  dataType: "json",
  prefix: ["article:", "blog:", "news:"],
  schema: s.object({
    title: s.string(),
    body: s.string(),
    author: s.string().noStem(),
    publishedAt: s.date().fast(),
    viewCount: s.number(),
  }),
});

```
</Tab>

<Tab title="Python">
```python {4}
articles = redis.search.create_index(
    name="articles",
    data_type="json",
    prefix=["article:", "blog:", "news:"],
    schema={
        "title": "TEXT",
        "body": "TEXT",
        "author": {"type": "TEXT", "nostem": True},
        "publishedAt": {"type": "DATE", "fast": True},
        "viewCount": "U64",
    },
)
```
</Tab>

</Tab>

</Tabs>

By default, when an index is created, all existing keys matching the specified type and prefixes are scanned and indexed.
Use `SKIPINITIALSCAN` to defer indexing, which is useful for large datasets where you want to start fresh or handle
existing data differently.

<Tabs>

<Tab title="TypeScript">
```ts {5}
const profiles = await redis.search.createIndex({
  name: "profiles",
  dataType: "string",
  prefix: "profiles:",
  skipInitialScan: true,
  schema: s.object({
    name: s.string(),
  }),
});
```
</Tab>

<Tab title="Python">
```python {5}
profiles = redis.search.create_index(
    name="profiles",
    data_type="string",
    prefixes="profiles:",
    skip_initial_scan=True,
    schema={
        "name": "TEXT",
    },
)
```
</Tab>

<Tab title="Redis CLI">
```bash
# Skipping initial scan and indexing of keys with SKIPINITIALSCAN
SEARCH.CREATE profiles ON STRING PREFIX 1 profiles: SKIPINITIALSCAN SCHEMA name TEXT
```
</Tab>

</Tabs>

It is possible to specify the language of the text fields, so that an appropriate tokenizer
and stemmer can be used. For more on tokenization and stemming, see the
[Text Field Options](./schema-definition#text-field-options) section.

When not specified, language defaults to `english`.

Currently, the following languages are supported:

* `english`
* `arabic`
* `danish`
* `dutch`
* `finnish`
* `french`
* `german`
* `greek`
* `hungarian`
* `italian`
* `norwegian`
* `portuguese`
* `romanian`
* `russian`
* `spanish`
* `swedish`
* `tamil`
* `turkish`

<Tabs>

<Tab title="TypeScript">
```ts {5}
const addresses = await redis.search.createIndex({
  name: "addresses",
  dataType: "json",
  prefix: "address:",
  language: "turkish",
  schema: s.object({
    address: s.string().noStem(),
    description: s.string(),
  }),
});

```
</Tab>

<Tab title="Python">
```python {5}
addresses = redis.search.create_index(
    name="addresses",
    data_type="json",
    prefix="address:",
    language="turkish",
    schema={
        "address": {"type": "TEXT", "nostem": True},
        "description": "TEXT",
    },
)
```
</Tab>

<Tab title="Redis CLI">
```bash
# Turkish language index
SEARCH.CREATE addresses ON JSON PREFIX 1 address: LANGUAGE turkish SCHEMA address TEXT NOSTEM description TEXT
```

</Tab>

</Tabs>

Finally, it is possible safely create an index only if it does not exist, using
the `EXISTOK` option.

<Tabs>

<Tab title="TypeScript">
```ts {5}
const cache = await redis.search.createIndex({
  name: "cache",
  dataType: "string",
  prefix: "cache:",
  existsOk: true,
  schema: s.object({
    content: s.string(),
  }),
});
```
</Tab>

<Tab title="Python">
```python {5}
cache = redis.search.create_index(
    name="cache",
    data_type="string",
    prefixes="cache:",
    exists_ok=True,
    schema={
        "content": "TEXT",
    },
)
```
</Tab>

<Tab title="Redis CLI">
```bash
# Safe creation with EXISTOK
SEARCH.CREATE cache ON STRING PREFIX 1 cache: EXISTSOK SCHEMA content TEXT
```
</Tab>

</Tabs>

For the schema definition of the index, see the [Schema Definition](./schema-definition) section.

### Getting an Index Client

The `redis.search.index()` method creates a client for an existing index without making a Redis call. This is useful when you want to query or manage an index that already exists, without the overhead of creating it.

<Tabs>

<Tab title="TypeScript">
```ts {5-6,23}
import { Redis, s } from "@upstash/redis";

const redis = Redis.fromEnv();

// Get a client for an existing index
const users = redis.search.index({ name: "users" });

// Query the index
const results = await users.query({
  filter: { name: "John" },
});

// With schema for type safety
const userSchema = s.object({
  name: s.string(),
  email: s.string(),
  age: s.number(),
});

// Note: The schema parameter provides TypeScript type safety
// for queries and results. It does not validate against the
// server-side index schema.
const typedUsers = redis.search.index({ name: "users", schema: userSchema });

// Now queries are type-safe
const typedResults = await typedUsers.query({
  filter: { name: "John" },
});

```
</Tab>

<Tab title="Python">
```python {5-6}
from upstash_redis import Redis

redis = Redis.from_env()

# Get a client for an existing index
users = redis.search.index(name="users")

# Query the index
results = users.query(filter={"name": "John"})
```
</Tab>

</Tabs>

This method is different from `redis.search.createIndex()` which:
* Creates a new index if it doesn't exist
* Makes a Redis call to create the index
* Returns an error if the index already exists (unless `EXISTOK` is used)

Use `redis.search.index()` when:
* The index already exists
* You want to avoid unnecessary Redis calls
* You're querying or managing an existing index

Use `redis.search.createIndex()` when:
* You need to create a new index
* You're setting up your application for the first time

### Describing an Index

The `SEARCH.DESCRIBE` command returns detailed information about an index, or `null` if the index doesn't exist.

<Tabs>

<Tab title="TypeScript">
```ts
const description = await index.describe();
// Returns IndexDescription or null if the index doesn't exist
```

</Tab>

<Tab title="Python">
```python
description = index.describe()
# Returns IndexDescription or None if the index doesn't exist
```

</Tab>

<Tab title="Redis CLI">
```bash
SEARCH.DESCRIBE index
```
</Tab>

</Tabs>

On response, the following information is returned:

| Field      | Description                              |
| ---------- | ---------------------------------------- |
| `name`     | Index name                               |
| `type`     | Data type (`STRING`, `HASH`, or `JSON`)  |
| `prefixes` | List of tracked key prefixes             |
| `language` | Stemming language                        |
| `schema`   | Field definitions with types and options |

### Dropping an Index

The `SEARCH.DROP` command removes an index and stops tracking associated keys.

Returns `1` if the index was dropped, or `0` if the index was not found.

<Tabs>

<Tab title="TypeScript">
```ts
const result = await index.drop();
// Returns 1 (dropped) or 0 (index not found)
```
</Tab>

<Tab title="Python">
```python
result = index.drop()
# Returns 1 (dropped) or 0 (index not found)
```
</Tab>

<Tab title="Redis CLI">
```bash
SEARCH.DROP index
```
</Tab>

</Tabs>

Note that, dropping an index only removes the search index. The underlying Redis keys are not affected.

### Waiting for Indexing

For adequate performance, index updates are batched and committed periodically. This means recent writes may not
immediately appear in search results. Use `SEARCH.WAITINDEXING` when you need to ensure queries reflect recent changes.

The `SEARCH.WAITINDEXING` command blocks until all pending index updates are processed and visible to queries.
For examples of changing, deleting, and expiring indexed documents, see [Document Updates](/docs/redis/search/document-updates).

We recommend **not to** call this command each time you perform a write operation on the index. For optimal indexing and
query performance, batch updates are necessary. This command is primarily useful in tests and CI pipelines
where you need to guarantee that writes are reflected in subsequent queries.

Returns `1` when indexing is complete, or `0` if the index was not found.

<Tabs>

<Tab title="TypeScript">
```ts
// Add new document
await redis.json.set("product:new", "$", { name: "New Product", price: 49.99 });

// Ensure it's searchable before querying
const result = await index.waitIndexing();
// Returns 1 (indexing complete) or 0 (index not found)

// Now the query will include the new product
const products = await index.query({
  filter: { name: "new" },
});

for (const product of products) {
  console.log(product);
}

```
</Tab>

<Tab title="Python">
```python
# Add new document
redis.json().set("product:new", "$", {"name": "New Product", "price": 49.99})

# Ensure it's searchable before querying
result = index.wait_indexing()
# Returns 1 (indexing complete) or 0 (index not found)

# Now the query will include the new product
products = index.query(filter={"name": "new"})

for product in products:
    print(product)
```
</Tab>

<Tab title="Redis CLI">
```bash
# Add new document
JSON.SET product:new $ '{"name": "New Product", "price": 49.99}'

# Ensure it's searchable before querying
SEARCH.WAITINDEXING products

# Now the query will include the new product
SEARCH.QUERY products '{"name": "new"}'
```

</Tab>

</Tabs>

# Introduction
Source: https://upstash.com/docs/redis/search/introduction

Upstash Redis Search is our first extension beyond the official Redis spec. Using the Rust-based Tantivy under the hood, we provide an extremely fast way to search through Redis data.

<img />

* **Easy Integration**: Works with JSON, Hashes and Strings out of the box
* **Auto-Synchronization**: Once you created an index, all write operations are automatically tracked
* **Intuitive Query Language**: A type-safe JSON-based query syntax with boolean operators, fuzzy matching, phrase queries,
  regex support, and more.
* **Production-Ready Performance**: Built on Tantivy, a fast full-text search engine library written in Rust

## Next Steps

<CardGroup cols={2}>
  <Card
    title="Getting Started"
    icon="rocket"
    href="/redis/search/getting-started"
  >
    Create your first index and run a query in a few lines of code
  </Card>
  <Card
    title="Schema Definition"
    icon="table-columns"
    href="/redis/search/schema-definition"
  >
    Define the fields you want to index and how they are matched
  </Card>
  <Card
    title="Querying"
    icon="magnifying-glass"
    href="/redis/search/querying"
  >
    Learn the JSON-based query language with filters and operators
  </Card>
  <Card
    title="Recipes"
    icon="book-open"
    href="/redis/search/recipes/overview"
  >
    Complete, real-world examples you can adapt to your own use cases
  </Card>
</CardGroup>

# $boost
Source: https://upstash.com/docs/redis/search/query-operators/boolean-operators/boost

The `$boost` operator adjusts the score contribution of a boolean clause.
Use it to fine-tune how much weight specific conditions have in the overall relevance ranking.

By default, all matching conditions contribute equally to a document's relevance score.
The `$boost` operator multiplies a clause's score contribution by the specified factor:

* **Values greater than 1** increase importance (e.g., `$boost: 5.0` makes the clause 5x more important)
* **Values between 0 and 1** decrease importance
* **Negative values** demote matches, pushing them lower in results

The most common use case is boosting specific `$should` conditions to prioritize certain matches:

```ts
{
  $must: { category: "electronics" },
  $should: [
    { description: "premium", $boost: 10.0 },  // High priority
    { description: "featured", $boost: 5.0 },  // Medium priority
    { description: "sale" }                    // Normal priority (default boost: 1.0)
  ]
}
```

Documents matching "premium" rank significantly higher than those matching only "sale".

Negative boost values demote matches without excluding them entirely.
This is useful when you want to push certain results lower without filtering them out:

```ts
{
  $must: { category: "electronics" },
  $should: {
    description: "budget",
    $boost: -2.0  // Push budget items lower in results
  }
}
```

Unlike `$mustNot`, which excludes documents entirely, negative boosting keeps documents in results but ranks them lower.

### Examples

<Tabs>

<Tab title="TypeScript">
```ts
// Prioritize wireless and in-stock items
await products.query({
  filter: {
    $must: {
      name: "headphones",
    },
    $should: {
      description: "wireless",
      inStock: true,
      $boost: 5.0,
    },
  },
});

// Demote budget items without excluding them
await products.query({
  filter: {
    $must: {
      category: "electronics",
    },
    $should: {
      description: "budget",
      $boost: -1.0,
    },
  },
});
```
</Tab>

<Tab title="Python">
```python
# Prioritize wireless and in-stock items
products.query(filter={
    "$must": {"name": "headphones"},
    "$should": {"description": "wireless", "inStock": True, "$boost": 5.0},
})

# Demote budget items without excluding them
products.query(filter={
    "$must": {"category": "electronics"},
    "$should": {"description": "budget", "$boost": -1.0},
})
```
</Tab>

<Tab title="Redis CLI">
```bash
# Prioritize wireless and in-stock items
SEARCH.QUERY products '{"$must": {"name": "headphones"}, "$should": {"description": "wireless", "inStock": true, "$boost": 5.0}}'

# Demote budget items without excluding them
SEARCH.QUERY products '{"$must": {"category": "electronics"}, "$should": {"description": "budget", "$boost": -1.0}}'
```
</Tab>

</Tabs>

# $must
Source: https://upstash.com/docs/redis/search/query-operators/boolean-operators/must

The `$must` operator requires all specified conditions to match.
Documents are only included in results if they satisfy every condition within the `$must` clause.
This implements logical AND behavior.

When you specify multiple field conditions at the top level of a query without any boolean operator,
they are implicitly wrapped in a `$must`. These queries are equivalent:

```ts
// Implicit must
{ name: "headphones", inStock: true }

// Explicit $must
{ $must: { name: "headphones", inStock: true } }
```

### Syntax Options

The `$must` operator accepts either an object or an array:

* **Object syntax**: Each key-value pair is a condition that must match
* **Array syntax**: Each element is a separate condition object that must match

Array syntax is useful when you have multiple conditions on the same field
or when building queries programmatically.

### Examples

<Tabs>

<Tab title="TypeScript">
```ts
// Explicit $must
await products.query({
  filter: {
    $must: [{ name: "headphones" }, { inStock: true }],
  },
});

// Equivalent implicit form
await products.query({
  filter: {
    name: "headphones",
    inStock: true,
  },
});

// $must with object syntax
await products.query({
  filter: {
    $must: {
      name: "headphones",
      inStock: true,
    },
  },
});
```
</Tab>

<Tab title="Python">
```python
# Explicit $must
products.query(filter={"$must": [{"name": "headphones"}, {"inStock": True}]})

# Equivalent implicit form
products.query(filter={"name": "headphones", "inStock": True})

# $must with object syntax
products.query(filter={"$must": {"name": "headphones", "inStock": True}})
```
</Tab>

<Tab title="Redis CLI">
```bash
# Explicit $must
SEARCH.QUERY products '{"$must": [{"name": "headphones"}, {"inStock": true}]}'

# Equivalent implicit form
SEARCH.QUERY products '{"name": "headphones", "inStock": true}'

# $must with object syntax
SEARCH.QUERY products '{"$must": {"name": "headphones", "inStock": true}}'
```
</Tab>

</Tabs>

# $mustNot
Source: https://upstash.com/docs/redis/search/query-operators/boolean-operators/must-not

The `$mustNot` operator excludes documents that match any of the specified conditions.
It acts as a filter, removing matching documents from the result set.

The `$mustNot` operator only filters results—it never adds documents to the result set.
This means it must be combined with `$must` or `$should` to define which documents to search.

A query with only `$mustNot` returns no results because there is no base set to filter:

```ts
// This returns NO results - nothing to filter
{ $mustNot: { category: "electronics" } }

// This works - $must provides the base set, $mustNot filters it
{ $must: { inStock: true }, $mustNot: { category: "electronics" } }
```

### Excluding Multiple Conditions

When `$mustNot` contains multiple conditions (via array or object), documents matching ANY of those conditions are excluded.
This is effectively an OR within the exclusion:

```ts
// Exclude documents that match category="generic" OR price > 500
{ $mustNot: [{ category: "generic" }, { price: { $gt: 500 } }] }
```

### Examples

<Tabs>

<Tab title="TypeScript">
```ts
// Exclude out-of-stock items
await products.query({
  filter: {
    $must: {
      category: "electronics",
    },
    $mustNot: {
      inStock: false,
    },
  },
});

// Exclude multiple conditions
await products.query({
  filter: {
    $must: {
      name: "headphones",
    },
    $mustNot: [{ category: "generic" }, { price: { $gt: 500 } }],
  },
});
```
</Tab>

<Tab title="Python">
```python
# Exclude out-of-stock items
products.query(filter={"$must": {"category": "electronics"}, "$mustNot": {"inStock": False}})

# Exclude multiple conditions
products.query(filter={
    "$must": {"name": "headphones"},
    "$mustNot": [{"category": "generic"}, {"price": {"$gt": 500}}],
})
```
</Tab>

<Tab title="Redis CLI">
```bash
# Exclude out-of-stock items
SEARCH.QUERY products '{"$must": {"category": "electronics"}, "$mustNot": {"inStock": false}}'

# Exclude multiple conditions
SEARCH.QUERY products '{"$must": {"name": "headphones"}, "$mustNot": [{"category": "generic"}, {"price": {"$gt": 500}}]}'
```
</Tab>

</Tabs>

# Overview
Source: https://upstash.com/docs/redis/search/query-operators/boolean-operators/overview

Boolean operators combine multiple conditions to build complex queries.
They control how individual field conditions are logically combined to determine which documents match.

### Available Operators

| Operator | Description |
|----------|-------------|
| [`$must`](./must) | All conditions must match |
| [`$should`](./should) | At least one condition should match, or acts as a score booster when combined with `$must` |
| [`$mustNot`](./must-not) | Excludes documents matching any condition |
| [`$boost`](./boost) | Adjusts the score contribution of a boolean clause |

### How Boolean Operators Work Together

Boolean operators can be combined in a single query to express complex logic.
The operators work together as follows:

1. **`$must`** defines the required conditions. Documents must match ALL of these.
2. **`$should`** adds optional conditions:
   * When used alone: documents must match at least one condition
   * When combined with `$must`: conditions become optional score boosters
3. **`$mustNot`** filters out unwanted documents from the result set.

### Combining Operators

Here's an example that uses all three operators together:

<Tabs>

<Tab title="TypeScript">
```ts
// Find in-stock electronics, preferring wireless products, excluding budget items
await products.query({
  filter: {
    $must: {
      category: "electronics",
      inStock: true,
    },
    $should: [
      { name: "wireless" },
      { description: "bluetooth" },
    ],
    $mustNot: {
      description: "budget",
    },
  },
});
```
</Tab>

<Tab title="Python">
```python
# Find in-stock electronics, preferring wireless products, excluding budget items
products.query(filter={
    "$must": {"category": "electronics", "inStock": True},
    "$should": [{"name": "wireless"}, {"description": "bluetooth"}],
    "$mustNot": {"description": "budget"},
})
```
</Tab>

<Tab title="Redis CLI">
```bash
# Find in-stock electronics, preferring wireless products, excluding budget items
SEARCH.QUERY products '{"$must": {"category": "electronics", "inStock": true}, "$should": [{"name": "wireless"}, {"description": "bluetooth"}], "$mustNot": {"description": "budget"}}'
```
</Tab>

</Tabs>

This query:
1. **Requires** documents to be in the "electronics" category AND in stock
2. **Boosts** documents that mention "wireless" or "bluetooth" (but doesn't require them)
3. **Excludes** any documents containing "budget" in the description

### Nesting Boolean Operators

Boolean operators can be nested to create more complex logic:

<Tabs>

<Tab title="TypeScript">
```ts
// Find products that are either (premium electronics) OR (discounted sports items)
await products.query({
  filter: {
    $should: [
      {
        $must: {
          category: "electronics",
          description: "premium",
        },
      },
      {
        $must: {
          category: "sports",
          price: { $lt: 50 },
        },
      },
    ],
  },
});
```
</Tab>

<Tab title="Python">
```python
# Find products that are either (premium electronics) OR (discounted sports items)
products.query(filter={
    "$should": [
        {"$must": {"category": "electronics", "description": "premium"}},
        {"$must": {"category": "sports", "price": {"$lt": 50}}},
    ],
})
```
</Tab>

<Tab title="Redis CLI">
```bash
# Find products that are either (premium electronics) OR (discounted sports items)
SEARCH.QUERY products '{"$should": [{"$must": {"category": "electronics", "description": "premium"}}, {"$must": {"category": "sports", "price": {"$lt": 50}}}]}'
```
</Tab>

</Tabs>

# $should
Source: https://upstash.com/docs/redis/search/query-operators/boolean-operators/should

The `$should` operator specifies conditions where at least one should match.
Its behavior changes depending on whether it's used alone or combined with `$must`.

When `$should` is the only boolean operator in a query, it acts as a logical OR.
Documents must match at least one of the conditions to be included in results:

```ts
// Match documents in electronics OR sports category
{ $should: [{ category: "electronics" }, { category: "sports" }] }
```

Documents matching more conditions score higher than those matching fewer.

When `$should` is combined with `$must`, the `$should` conditions become optional score boosters.
Documents are not required to match the `$should` conditions, but those that do receive higher relevance scores:

```ts
{
  $must: { category: "electronics" },    // Required: must be electronics
  $should: { description: "premium" }    // Optional: boosts score if present
}
```

This is useful for influencing result ranking without restricting the result set.

When multiple `$should` conditions are specified, each matching condition adds to the document's score.
Documents matching more conditions rank higher:

```ts
{
  $must: { category: "electronics" },
  $should: [
    { name: "wireless" },       // +score if matches
    { description: "bluetooth" }, // +score if matches
    { description: "premium" }    // +score if matches
  ]
}
```

A document matching all three `$should` conditions scores higher than one matching only one.

### Syntax Options

The `$should` operator accepts either an object or an array:

* **Object syntax**: Each key-value pair is a condition that should match
* **Array syntax**: Each element is a separate condition object that should match

Array syntax is useful when you have multiple conditions on the same field
or when building queries programmatically.

### Examples

<Tabs>

<Tab title="TypeScript">
```ts
// Match either condition
await products.query({
  filter: {
    $should: [{ category: "electronics" }, { category: "sports" }],
  },
});

// Optional boost: "wireless" is required, "premium" boosts score if present
await products.query({
  filter: {
    $must: {
      name: "wireless",
    },
    $should: {
      description: "premium",
    },
  },
});

// Multiple optional boosters
await products.query({
  filter: {
    $must: {
      category: "electronics",
    },
    $should: [
      { name: "wireless" },
      { description: "bluetooth" },
      { description: "premium" },
    ],
  },
});
```
</Tab>

<Tab title="Python">
```python
# Match either condition
products.query(filter={"$should": [{"category": "electronics"}, {"category": "sports"}]})

# Optional boost: "wireless" is required, "premium" boosts score if present
products.query(filter={"$must": {"name": "wireless"}, "$should": {"description": "premium"}})

# Multiple optional boosters
products.query(filter={
    "$must": {"category": "electronics"},
    "$should": [
        {"name": "wireless"},
        {"description": "bluetooth"},
        {"description": "premium"},
    ],
})
```
</Tab>

<Tab title="Redis CLI">
```bash
# Match either condition
SEARCH.QUERY products '{"$should": [{"category": "electronics"}, {"category": "sports"}]}'

# Optional boost: "wireless" is required, "premium" boosts score if present
SEARCH.QUERY products '{"$must": {"name": "wireless"}, "$should": {"description": "premium"}}'

# Multiple optional boosters
SEARCH.QUERY products '{"$must": {"category": "electronics"}, "$should": [{"name": "wireless"}, {"description": "bluetooth"}, {"description": "premium"}]}'
```
</Tab>

</Tabs>

# $boost
Source: https://upstash.com/docs/redis/search/query-operators/field-operators/boost

The `$boost` operator adjusts the relevance score contribution of a field match.
This allows you to prioritize certain matches over others in the result ranking.

### How Boosting Works

Search results are ordered by a relevance score that reflects how well each document matches the query.
By default, all matching conditions contribute equally to this score.
The `$boost` operator multiplies a match's score contribution by the specified factor.

* **Positive values greater than 1** increase the match's importance (e.g., `$boost: 2.0` doubles the contribution)
* **Values between 0 and 1** decrease the match's importance
* **Negative values** demote matches, pushing them lower in results

### Use Cases

* **Prioritize premium content:** Boost matches in title fields over body text
* **Promote featured items:** Give higher scores to promoted products
* **Demote less relevant matches:** Use negative boosts to push certain matches down

### Compatibility

The `$boost` operator can be used with any field type since it modifies the score rather than the matching behavior.

| Field Type | Supported |
|------------|-----------|
| TEXT | Yes |
| U64/I64/F64 | Yes |
| DATE | Yes |
| BOOL | Yes |
| KEYWORD | Yes |
| FACET | Yes |

### Examples

<Tabs>

<Tab title="TypeScript">
```ts
// Boost matches in $should clauses to prioritize certain terms
await products.query({
  filter: {
    $must: {
      inStock: true,
    },
    $should: [
      { description: "premium", $boost: 10.0 },
      { description: "quality", $boost: 5.0 },
    ],
  },
});

// Demote budget items with negative boost
await products.query({
  filter: {
    $must: {
      category: "electronics",
    },
    $should: [
      { name: "featured", $boost: 5.0 },
      { description: "budget", $boost: -2.0 },
    ],
  },
});
```
</Tab>

<Tab title="Python">
```python
# Boost matches in $should clauses to prioritize certain terms
products.query(filter={
    "$must": {"inStock": True},
    "$should": [
        {"description": "premium", "$boost": 10.0},
        {"description": "quality", "$boost": 5.0},
    ],
})

# Demote budget items with negative boost
products.query(filter={
    "$must": {"category": "electronics"},
    "$should": [
        {"name": "featured", "$boost": 5.0},
        {"description": "budget", "$boost": -2.0},
    ],
})
```
</Tab>

<Tab title="Redis CLI">
```bash
# Boost matches in $should clauses to prioritize certain terms
SEARCH.QUERY products '{"$must": {"inStock": true}, "$should": [{"description": "premium", "$boost": 10.0}, {"description": "quality", "$boost": 5.0}]}'

# Demote budget items with negative boost
SEARCH.QUERY products '{"$must": {"category": "electronics"}, "$should": [{"name": "featured", "$boost": 5.0}, {"description": "budget", "$boost": -2.0}]}'
```
</Tab>

</Tabs>

# $eq
Source: https://upstash.com/docs/redis/search/query-operators/field-operators/eq

The `$eq` operator performs explicit equality matching on a field.
While you can often omit `$eq` and pass values directly (e.g., `{ price: 199.99 }`),
using `$eq` explicitly makes your intent clear and is required when combining with other operators.

For **text fields**, `$eq` performs a term search for single words.
For multi-word values, it behaves like a phrase query, requiring the words to appear adjacent and in order.
For **numeric fields**, it matches the exact value.
For **boolean fields**, it matches `true` or `false`.
For **date fields**, it matches the exact timestamp.

### Compatibility

| Field Type | Supported |
|------------|-----------|
| TEXT | Yes |
| U64/I64/F64 | Yes |
| DATE | Yes |
| BOOL | Yes |
| KEYWORD | Yes |
| FACET | Yes |

### Examples

<Tabs>

<Tab title="TypeScript">
```ts
// Text field
await products.query({
  filter: {
    name: { $eq: "wireless headphones" },
  },
});

// Numeric field
await products.query({
  filter: {
    price: { $eq: 199.99 },
  },
});

// Boolean field
await products.query({
  filter: {
    inStock: { $eq: true },
  },
});

// Date field
await users.query({
  filter: {
    createdAt: { $eq: "2024-01-15T00:00:00Z" },
  },
});
```
</Tab>

<Tab title="Python">
```python
# Text field
products.query(filter={"name": {"$eq": "wireless headphones"}})

# Numeric field
products.query(filter={"price": {"$eq": 199.99}})

# Boolean field
products.query(filter={"inStock": {"$eq": True}})

# Date field
users.query(filter={"createdAt": {"$eq": "2024-01-15T00:00:00Z"}})
```
</Tab>

<Tab title="Redis CLI">
```bash
# Text field
SEARCH.QUERY products '{"name": {"$eq": "wireless headphones"}}'

# Numeric field
SEARCH.QUERY products '{"price": {"$eq": 199.99}}'

# Boolean field
SEARCH.QUERY products '{"inStock": {"$eq": true}}'

# Date field
SEARCH.QUERY users '{"createdAt": {"$eq": "2024-01-15T00:00:00Z"}}'
```
</Tab>

</Tabs>

# $fuzzy
Source: https://upstash.com/docs/redis/search/query-operators/field-operators/fuzzy

The `$fuzzy` operator matches terms that are similar but not identical to the search term.
This is useful for handling typos, misspellings, and minor variations in user input.

### Levenshtein Distance

Fuzzy matching uses Levenshtein distance (also called edit distance) to measure similarity between terms.
The distance is the minimum number of single-character edits needed to transform one word into another.
These edits include:

* **Insertions:** Adding a character ("headphone" → "headphones")
* **Deletions:** Removing a character ("headphones" → "headphone")
* **Substitutions:** Replacing a character ("headphones" → "headphonez")

For example, the Levenshtein distance between "headphons" and "headphones" is 1 (one insertion needed).

### Distance Parameter

The `distance` parameter sets the maximum Levenshtein distance allowed for a match.
The default is 1, and the maximum allowed value is 2.

| Distance | Matches |
|----------|---------|
| 1 | Words with 1 edit (handles most single typos) |
| 2 | Words with up to 2 edits (handles more severe misspellings) |

Higher distances match more terms but may include unintended matches, so use distance 2 only when needed.

### Transposition Cost

A transposition swaps two adjacent characters (e.g., "teh" → "the").
By default, a transposition counts as 1 edit.
Setting `transpositionCostOne: false` counts transpositions as two edits (one deletion + one insertion) instead.

For example, searching for "haedphone" to find "headphone":
* With `transpositionCostOne: true`: Distance is 1 (swap counts as 1)
* Without `transpositionCostOne`: Distance is 2 (swap "ae" → "ea" costs 2)

This is useful when users commonly transpose characters while typing quickly.

### Prefix Matching

Setting `prefix: true` enables fuzzy prefix matching, which matches terms that start with a fuzzy
variation of the search term. This combines the typo tolerance of fuzzy matching with prefix
matching for incomplete words.

For example, searching for "headpho" with `prefix: true`:
* Matches "headphones" (prefix match)
* Matches "headphone" (prefix match)
* Matches "haedphones" with `transpositionCostOne: true` (fuzzy prefix, handles typo + incomplete word)

This is particularly useful for search-as-you-type autocomplete where users may have typos
in partially typed words.

### Multiple Words

When you provide multiple words to `$fuzzy`, each word is matched with fuzzy tolerance and combined using
a boolean [`$must`](../boolean-operators/must) query.
This means all terms must match (with their respective fuzzy tolerance) for a document to be returned.

For example, searching for "wireles headphons" will match documents containing both "wireless" and "headphones", even with the typos.

### Compatibility

| Field Type | Supported |
|------------|-----------|
| TEXT | Yes |
| U64/I64/F64 | No |
| DATE | No |
| BOOL | No |
| KEYWORD | No |
| FACET | No |

### Examples

<Tabs>

<Tab title="TypeScript">
```ts
// Simple fuzzy (distance 1, handles single typos)
// Matches "headphone" even with the typo "headphon"
await products.query({
  filter: {
    name: { $fuzzy: "headphon" },
  },
});

// Custom distance for more tolerance
// "haedphone" is 2 edits away from "headphone" without taking transposition into account
await products.query({
  filter: {
    name: {
      $fuzzy: {
        value: "haedphone",
        distance: 2,
        transpositionCostOne: false,
      },
    },
  },
});

// Handle character transpositions efficiently
// "haedphone" has swapped "ae", with transpositionCostOne this is 1 edit
await products.query({
  filter: {
    name: {
      $fuzzy: {
        value: "haedphone",
        distance: 1,
        transpositionCostOne: true,
      },
    },
  },
});

// Combine prefix with transposition for robust autocomplete
// Handles both typos and incomplete input like "haedpho" → "headphones"
await products.query({
  filter: {
    name: {
      $fuzzy: {
        value: "haedpho",
        prefix: true,
      },
    },
  },
});

// Multiple words - matches documents containing both terms (with fuzzy tolerance)
// Matches "wireless headphones" even with typos in both words
await products.query({
  filter: {
    name: { $fuzzy: "wireles headphons" },
  },
});
```
</Tab>

<Tab title="Python">
```python
# Simple fuzzy (distance 1, handles single typos)
products.query(filter={"name": {"$fuzzy": "headphon"}})

# Custom distance for more tolerance
products.query(filter={"name": {"$fuzzy": {"value": "haedphone", "distance": 2, "transpositionCostOne": False}}})

# Handle character transpositions efficiently
products.query(filter={"name": {"$fuzzy": {"value": "haedphone", "distance": 1, "transpositionCostOne": True}}})

# Combine prefix with transposition for robust autocomplete
products.query(filter={"name": {"$fuzzy": {"value": "haedpho", "prefix": True}}})

# Multiple words - matches documents containing both terms (with fuzzy tolerance)
products.query(filter={"name": {"$fuzzy": "wireles headphons"}})
```
</Tab>

<Tab title="Redis CLI">
```bash
# Simple fuzzy (distance 1, handles single typos)
SEARCH.QUERY products '{"name": {"$fuzzy": "headphon"}}'

# Custom distance for more tolerance
SEARCH.QUERY products '{"name": {"$fuzzy": {"value": "haedphone", "distance": 2, "transpositionCostOne": false}}}'

# Handle character transpositions efficiently
SEARCH.QUERY products '{"name": {"$fuzzy": {"value": "haedphone", "distance": 1, "transpositionCostOne": true}}}'

# Combine prefix with transposition for robust autocomplete
SEARCH.QUERY products '{"name": {"$fuzzy": {"value": "haedpho", "prefix": true, "transpositionCostOne": true}}}'

# Multiple words - matches documents containing both terms (with fuzzy tolerance)
SEARCH.QUERY products '{"name": {"$fuzzy": "wireles headphons"}}'
```
</Tab>

</Tabs>

# $in
Source: https://upstash.com/docs/redis/search/query-operators/field-operators/in

The `$in` operator matches documents where the field value equals any one of the specified values.
This is useful when you want to filter by multiple acceptable values without writing separate conditions.

The operator takes an array of values and returns documents where the field matches at least one value in the array.
This is equivalent to combining multiple `$eq` conditions with a logical OR.

### Compatibility

| Field Type | Supported |
|------------|-----------|
| TEXT | Yes |
| U64/I64/F64 | Yes |
| DATE | Yes |
| BOOL | Yes |
| KEYWORD | Yes |
| FACET | Yes |

### Examples

<Tabs>

<Tab title="TypeScript">
```ts
// Match any of several categories
await products.query({
  filter: {
    category: {
      $in: ["electronics", "accessories", "audio"],
    },
  },
});
```
</Tab>

<Tab title="Python">
```python
# Match any of several categories
products.query(filter={"category": {"$in": ["electronics", "accessories", "audio"]}})
```
</Tab>

<Tab title="Redis CLI">
```bash
# Match any of several categories
SEARCH.QUERY products '{"category": {"$in": ["electronics", "accessories", "audio"]}}'
```
</Tab>

</Tabs>

# Overview
Source: https://upstash.com/docs/redis/search/query-operators/field-operators/overview

Field operators provide precise control over how individual fields are matched.
Use these when simple value matching doesn't meet your needs.

### Quick Reference

| Operator | Supported Field Types | Description | Example |
|---|---|---|---|
| [`$smart`](./smart-matching) | all | Intelligent multi-stage matching (default behavior) | `{"name": {"$smart": "wireless"}}` |
| [`$eq`](./eq) | all | Exact equality | `{"status": {"$eq": "active"}}` |
| [`$in`](./in) | all | Match any of multiple values | `{"status": {"$in": ["active", "pending"]}}` |
| [`$gt`](./range-operators), `$gte`, `$lt`, `$lte` | numeric, date, keyword | Range comparison | `{"price": {"$gt": 10, "$lt": 100}}` |
| [`$phrase`](./phrase) | text | Phrase matching with optional slop and prefix | `{"text": {"$phrase": {"query": "hello world", "slop": 1}}}` |
| [`$fuzzy`](./fuzzy) | text | Typo-tolerant matching (Levenshtein distance) | `{"name": {"$fuzzy": {"term": "wireles", "distance": 1}}}` |
| [`$regex`](./regex) | text | Regular expression pattern matching | `{"name": {"$regex": "wire.*"}}` |
| [`$boost`](./boost) | modifier (on any operator) | Adjust relevance score weight | `{"name": {"$eq": "wireless", "$boost": 2.0}}` |

# $phrase
Source: https://upstash.com/docs/redis/search/query-operators/field-operators/phrase

The `$phrase` operator matches documents where terms appear in a specific sequence.
Unlike a simple multi-term search that finds documents containing all terms anywhere,
phrase matching requires the terms to appear in the exact order specified.

### Simple Form

In its simplest form, `$phrase` takes a string value and requires the terms to appear adjacent to each other in order:

```
{ $phrase: "wireless headphones" }
```

This matches "wireless headphones" but not "wireless bluetooth headphones" or "headphones wireless".

### Slop Parameter

The `slop` parameter allows flexibility in phrase matching by permitting other words to appear between your search terms.
The slop value represents the maximum number of position moves allowed to match the phrase.

For example, with `slop: 2`:
* "wireless headphones" matches (0 moves needed)
* "wireless bluetooth headphones" matches (1 move: "headphones" shifted 1 position)
* "wireless bluetooth overhead headphones" matches (2 moves)
* "wireless bluetooth noise-cancelling headphones" does NOT match (requires 3 moves)

A slop of 0 requires exact adjacency (the default behavior).

### Prefix Parameter

The `prefix` parameter allows the last term to match as a prefix.
This is useful for autocomplete scenarios where users might not complete the final word:

```
description: { $phrase: { value: "wireless head", prefix: true } }
```

This matches "wireless headphones", "wireless headset", etc.

**Note:** You can use either `slop` or `prefix`, but not both in the same query.

### Compatibility

| Field Type | Supported |
|------------|-----------|
| TEXT | Yes |
| U64/I64/F64 | No |
| DATE | No |
| BOOL | No |
| KEYWORD | No |
| FACET | No |

### Examples

<Tabs>

<Tab title="TypeScript">
```ts
// Simple phrase (terms must be adjacent)
await products.query({
  filter: {
    description: {
      $phrase: "noise cancelling",
    },
  },
});

// With slop (allow terms between, not exact adjacency)
await products.query({
  filter: {
    description: {
      $phrase: {
        value: "wireless headphones",
        slop: 2,
      },
    },
  },
});

// Prefix matching (last term can be partial)
await products.query({
  filter: {
    name: {
      $phrase: {
        value: "wireless head",
        prefix: true,
      },
    },
  },
});
```
</Tab>

<Tab title="Python">
```python
# Simple phrase (terms must be adjacent)
products.query(filter={"description": {"$phrase": "noise cancelling"}})

# With slop (allow terms between, not exact adjacency)
products.query(filter={"description": {"$phrase": {"value": "wireless headphones", "slop": 2}}})

# Prefix matching (last term can be partial)
products.query(filter={"name": {"$phrase": {"value": "wireless head", "prefix": True}}})
```
</Tab>

<Tab title="Redis CLI">
```bash
# Simple phrase (terms must be adjacent)
SEARCH.QUERY products '{"description": {"$phrase": "noise cancelling"}}'

# With slop (allow terms between, not exact adjacency)
SEARCH.QUERY products '{"description": {"$phrase": {"value": "wireless headphones", "slop": 2}}}'

# Prefix matching (last term can be partial)
SEARCH.QUERY products '{"name": {"$phrase": {"value": "wireless head", "prefix": true}}}'
```
</Tab>

</Tabs>

# Range Operators
Source: https://upstash.com/docs/redis/search/query-operators/field-operators/range-operators

Range operators filter documents based on numeric or date field boundaries.
You can use them to find values within a range, above a threshold, or below a limit.

| Operator | Description | Example |
|----------|-------------|---------|
| `$gt` | Greater than (exclusive) | `price > 100` |
| `$gte` | Greater than or equal (inclusive) | `price >= 100` |
| `$lt` | Less than (exclusive) | `price < 200` |
| `$lte` | Less than or equal (inclusive) | `price <= 200` |

You can combine multiple range operators on the same field to create bounded ranges.
For example, `{ $gte: 100, $lte: 200 }` matches values from 100 to 200 inclusive.

For open-ended ranges, use a single operator.
For example, `{ $gt: 500 }` matches all values greater than 500 with no upper limit.

### Compatibility

| Field Type | Supported |
|------------|-----------|
| TEXT | No |
| U64/I64/F64 | Yes |
| DATE | Yes |
| BOOL | No |
| KEYWORD | Yes |
| FACET | No |

### Examples

<Tabs>

<Tab title="TypeScript">
```ts
// Price range
await products.query({
  filter: {
    price: { $gte: 100, $lte: 200 },
  },
});

// Open-ended range (no upper bound)
await products.query({
  filter: {
    price: { $gt: 500 },
  },
});

// Date range (no lower bound)
await users.query({
  filter: {
    createdAt: { $lt: "2024-02-01T00:00:00Z" },
  },
});
```
</Tab>

<Tab title="Python">
```python
# Price range
products.query(filter={"price": {"$gte": 100, "$lte": 200}})

# Open-ended range (no upper bound)
products.query(filter={"price": {"$gt": 500}})

# Date range (no lower bound)
users.query(filter={"createdAt": {"$lt": "2024-02-01T00:00:00Z"}})
```
</Tab>

<Tab title="Redis CLI">
```bash
# Price range
SEARCH.QUERY products '{"price": {"$gte": 100, "$lte": 200}}'

# Open-ended range (no upper bound)
SEARCH.QUERY products '{"price": {"$gt": 500}}'

# Date range (no lower bound)
SEARCH.QUERY users '{"createdAt": {"$lt": "2024-02-01T00:00:00Z"}}'
```
</Tab>

</Tabs>

# $regex
Source: https://upstash.com/docs/redis/search/query-operators/field-operators/regex

The `$regex` operator matches documents where field terms match a regular expression pattern.
This is useful for flexible pattern matching when exact values are unknown or when you need to match variations of a term.

### How Regex Matching Works

Regex patterns are matched against individual tokenized terms, not the entire field value.
Text fields are tokenized (split into words) during indexing, so the regex is applied to each term separately.

For example, if a document contains "hello world" in a text field:
* `{ $regex: "hel.*" }` matches (matches the "hello" term)
* `{ $regex: "hello world.*" }` does NOT match (regex cannot span multiple terms)
* `{ $regex: "wor.*" }` matches (matches the "world" term)

For exact phrase matching across multiple words, use the [$phrase](./phrase) operator instead.

### Performance Considerations

* **Avoid leading wildcards:** Patterns like `".*suffix"` require scanning all terms in the index and are slow.
  Prefer patterns that start with literal characters.

### Stemming Behavior

On fields with stemming enabled (the default), regex operates on the stemmed form of terms.
For example, "running" might be stored as "run", so a regex pattern `"running.*"` would not match.

To use regex reliably, consider using `NOSTEM` on fields where you need exact pattern matching.
See [Text Field Options](../../schema-definition#text-field-options) for more details.

### Compatibility

| Field Type | Supported |
|------------|-----------|
| TEXT | Yes |
| U64/I64/F64 | No |
| DATE | No |
| BOOL | No |
| KEYWORD | No |
| FACET | No |

### Examples

<Tabs>

<Tab title="TypeScript">
```ts
// Match categories starting with "e"
await products.query({
  filter: {
    category: {
      $regex: "e.*",
    },
  },
});

// Match email domains (requires NOTOKENIZE field)
await users.query({
  filter: {
    email: {
      $regex: ".*@company\\.com",
    },
  },
});

// Match product codes with pattern
await products.query({
  filter: {
    sku: {
      $regex: "SKU-[0-9]{4}",
    },
  },
});
```
</Tab>

<Tab title="Python">
```python
# Match categories starting with "e"
products.query(filter={"category": {"$regex": "e.*"}})

# Match email domains (requires NOTOKENIZE field)
users.query(filter={"email": {"$regex": ".*@company\\.com"}})

# Match product codes with pattern
products.query(filter={"sku": {"$regex": "SKU-[0-9]{4}"}})
```
</Tab>

<Tab title="Redis CLI">
```bash
# Match categories starting with "e"
SEARCH.QUERY products '{"category": {"$regex": "e.*"}}'

# Match email domains (requires NOTOKENIZE field)
SEARCH.QUERY users '{"email": {"$regex": ".*@company\\.com"}}'

# Match product codes with pattern
SEARCH.QUERY products '{"sku": {"$regex": "SKU-[0-9]{4}"}}'
```
</Tab>

</Tabs>

# Smart Matching
Source: https://upstash.com/docs/redis/search/query-operators/field-operators/smart-matching

When you provide a value directly to a field (without explicit operators like `$phrase` or `$fuzzy`),
the search engine applies smart matching. The behavior depends on the field type:

* **Numeric, boolean, and date fields**: Smart matching performs an exact equality check.
* **Text fields**: Smart matching applies intelligent matching strategies to find the most relevant results, as described below.

### Text Field Matching

For text fields, the matching behavior varies based on the input format.

### Single-Word Values

For single-word searches, the engine runs multiple matching strategies and combines their scores:

1. **Exact term match** (high boost): Documents containing the exact token score highest.

2. **Fuzzy match** (no boost): Documents containing terms within Levenshtein distance 1
   (with transpositions counting as a single edit) are included.

3. **Fuzzy prefix match** (no boost): Documents containing terms that start with a fuzzy
   variation of the search term are included. This handles incomplete words during typing.

```
{ name: "tabletop" }
```

This query returns results in roughly this order:
* "**tabletop**" (exact match)
* "**tabeltop**" (fuzzy match, 1 edit away)
* "**tabeltopping**" (fuzzy prefix match, incomplete word with typos matches full term)

### Multi-Word Values

For multi-word searches, the engine runs multiple matching strategies simultaneously and combines
their scores to surface the most relevant results:

1. **Exact phrase match** (highest boost): Documents where all words appear adjacent and in order
   score highest. Searching for `wireless headphones` ranks documents containing
   "wireless headphones" as a phrase above those with the words scattered.

2. **Exact phrase match with slop** (medium boost): Documents where all the query terms appear in
   order but not necessarily adjacent, allowing for a small number of intervening words—receive a boost.
   Searching for wireless headphones would rank documents containing `wireless bluetooth headphones`
   above those where the words are far apart, but below an exact phrase match (`wireless headphones`).

3. **Terms match** (medium boost): Documents containing all or some of the search terms, regardless of
   position or order, receive a moderate score boost.

3. **Fuzzy matching** (no boost): Documents containing terms similar to the search terms
   (accounting for typos) are included with a lower score.

4. **Fuzzy prefix on last word** (no boost): The last word is also matched with fuzzy prefix,
   handling incomplete words during search-as-you-type scenarios.

```
{ description: "wireless headphon" }
```

This query returns results in roughly this order:
* "Premium **wireless headphones** with noise cancellation" (phrase match with fuzzy prefix on last word)
* "**Headphones** with **wireless** connectivity" (all terms present, different order)
* "**Wireles headphone** with long battery" (fuzzy match for typos)

### Double-Quoted Phrases

Wrapping your search value in double quotes forces exact phrase matching.
The words must appear adjacent and in the exact order specified.

```
{ description: "\"noise cancelling\"" }
```

This matches only documents containing "noise cancelling" as an exact phrase.
It will NOT match:
* "noise and cancelling" (words not adjacent)
* "cancelling noise" (wrong order)
* "noise-cancelling" (hyphenated, tokenized differently)

This is useful when you need precise matching without the fuzzy tolerance of smart matching.

### The `$smart` Operator

Smart matching is applied implicitly when you provide a plain value to a field. You can also invoke it explicitly using the `$smart` operator. The behavior is identical — `$smart` is useful when you want to be more explicit about your intent, or when you need to combine smart matching with other operators like [`$boost`](./boost).

<Tabs>

<Tab title="TypeScript">
```ts
// Explicit smart matching
await index.query({
  filter: { name: { $smart: "wireless headphones" } },
});

// Combine smart matching with $boost
await index.query({
  filter: {
    $and: [
      { name: { $smart: "wireless headphones", $boost: 2.0 } },
      { description: { $smart: "noise cancelling" } },
    ],
  },
});
```
</Tab>

<Tab title="Python">
```python
# Explicit smart matching
index.query(filter={"name": {"$smart": "wireless headphones"}})

# Combine smart matching with $boost
index.query(filter={
    "$and": [
        {"name": {"$smart": "wireless headphones", "$boost": 2.0}},
        {"description": {"$smart": "noise cancelling"}},
    ],
})
```
</Tab>

<Tab title="Redis CLI">
```bash
# Explicit smart matching
SEARCH.QUERY products '{"name": {"$smart": "wireless headphones"}}'

# Combine smart matching with $boost
SEARCH.QUERY products '{"$and": [{"name": {"$smart": "wireless headphones", "$boost": 2.0}}, {"description": {"$smart": "noise cancelling"}}]}'
```
</Tab>

</Tabs>

### When to Use Explicit Operators

Smart matching works well for general search scenarios, but consider using explicit operators when you need:

* **Typo tolerance only**: Use [`$fuzzy`](./fuzzy) with specific distance settings
* **Phrase with gaps**: Use [`$phrase`](./phrase) with the `slop` parameter
* **Pattern matching**: Use [`$regex`](./regex) for regular expression patterns

# Queries
Source: https://upstash.com/docs/redis/search/querying

Queries are JSON strings that describe which documents to return. If the index doesn't exist, queries return `null`.

We recommend searching by field values directly because we automatically provide intelligent matching behavior out of the box:

<Tabs>

<Tab title="TypeScript">
```ts
// Basic search
await index.query({
  filter: { name: "headphones" },
});

// Search across multiple fields (implicit AND)
await index.query({
  filter: { name: "wireless", category: "electronics" },
});

// Search with exact values for non-text fields
await index.query({
  filter: { inStock: true, price: 199.99 },
});
```
</Tab>

<Tab title="Python">
```python
# Basic search
index.query(filter={"name": "headphones"})

# Search across multiple fields (implicit AND)
index.query(filter={"name": "wireless", "category": "electronics"})

# Search with exact values for non-text fields
index.query(filter={"inStock": True, "price": 199.99})
```
</Tab>

<Tab title="Redis CLI">
```bash
# Search for a term in a specific field
SEARCH.QUERY products '{"name": "headphones"}'

# Search across multiple fields (implicit AND)
SEARCH.QUERY products '{"name": "wireless", "category": "electronics"}'

# Search with exact values for non-text fields
SEARCH.QUERY products '{"inStock": true, "price": 199.99}'
```
</Tab>

</Tabs>

***

### Response Format

The query response is an array of matching documents. Each document includes the Redis key, a relevance score, and the document content.

<Tabs>

<Tab title="TypeScript">
```ts
const results = await index.query({
  filter: { name: "headphones" },
});

// results is an array of objects:
// [
//   { key: "product:1", score: 5.23, data: { name: "Wireless Headphones", price: 99.99, ... } },
//   { key: "product:2", score: 3.11, data: { name: "Studio Headphones", price: 149.99, ... } },
// ]
```
</Tab>

<Tab title="Python">
```python
results = index.query(filter={"name": "headphones"})

# results is a list of objects:
# [
#   QueryResult(key="product:1", score=5.23, data={"name": "Wireless Headphones", "price": 99.99, ...}),
#   QueryResult(key="product:2", score=3.11, data={"name": "Studio Headphones", "price": 149.99, ...}),
# ]
```
</Tab>

<Tab title="Redis CLI">
```bash
SEARCH.QUERY products '{"name": "headphones"}'

# Response:
# [
#   ["product:1", "5.23", [["$", "{\"name\": \"Wireless Headphones\", \"price\": 99.99}"]]],
#   ["product:2", "3.11", [["$", "{\"name\": \"Studio Headphones\", \"price\": 149.99}"]]]
# ]
```
</Tab>

</Tabs>

When `select` / `NOCONTENT` is used, the response shape changes — see [Controlling Output](#3-controlling-output).

If no documents match, an empty array is returned. If the index doesn't exist, `null` is returned.

For a detailed breakdown of the raw response structure, see the [Command Reference](/docs/redis/search/command-reference#searchquery).

***

### Smart Matching

When you provide a value directly to a field (without explicit operators),
we automatically apply [smart matching](./query-operators/field-operators/smart-matching).
For numeric, boolean, and date fields, this performs an exact equality check.
For text fields, it works like this:

* **Single-word values**: Performs a term search, matching the word against tokens in the field.
* **Multi-word values**: Combines phrase matching, term matching, and fuzzy matching with
  different boost weights to rank exact phrases highest while still finding partial matches.
* **Double-quoted phrases**: Forces exact phrase matching (e.g., `"\"noise cancelling\""` matches
  only those words adjacent and in order).

For more control, use explicit operators like [`$phrase`](./query-operators/field-operators/phrase),
or [`$fuzzy`](./query-operators/field-operators/fuzzy).

***

## Query Options

### 1. Pagination with Limit and Offset

Limit controls how many results to return. Offset controls how many results to skip. Together, they provide a way to paginate results.

| Parameter | Description | Default | Constraints |
|-----------|-------------|---------|-------------|
| `LIMIT` | Number of results to return | 10 | Must be between 1 and 1000 |
| `OFFSET` | Number of results to skip | 0 | Must be non-negative |

<Note>
`LIMIT` and `OFFSET` are separate keywords. This differs from RediSearch which uses the combined
`LIMIT <offset> <count>` syntax. Using `LIMIT 0 10` will return an error.
</Note>

<Tabs>

<Tab title="TypeScript">
```ts
// Page 1: first 10 results (with optional offset)
const page1 = await index.query({
  filter: { description: "wireless" },
  limit: 10,
});

// Page 2: results 11-20
const page2 = await index.query({
  filter: { description: "wireless" },
  limit: 10,
  offset: 10,
});

// Page 3: results 21-30
const page3 = await index.query({
  filter: { description: "wireless" },
  limit: 10,
  offset: 20,
});
```
</Tab>

<Tab title="Python">
```python
# Page 1: first 10 results
page1 = index.query(filter={"description": "wireless"}, limit=10)

# Page 2: results 11-20
page2 = index.query(filter={"description": "wireless"}, limit=10, offset=10)

# Page 3: results 21-30
page3 = index.query(filter={"description": "wireless"}, limit=10, offset=20)
```
</Tab>

<Tab title="Redis CLI">
```bash
# Page 1: first 10 results (with optional offset)
SEARCH.QUERY products '{"description": "wireless"}' LIMIT 10

# Page 2: results 11-20
SEARCH.QUERY products '{"description": "wireless"}' LIMIT 10 OFFSET 10

# Page 3: results 21-30
SEARCH.QUERY products '{"description": "wireless"}' LIMIT 10 OFFSET 20
```
</Tab>

</Tabs>

### 2. Sorting Results

Normally, search results are sorted in descending order of query relevance.

It is possible to override this, and sort the results by a certain field
in ascending or descending order.

Only fields defined as `.fast()` in the schema can be used as the sort field (enabled by default).

When using `orderBy`, the score in results reflects the sort field's value rather than relevance.

<Tabs>

<Tab title="TypeScript">
```ts
// Sort by price, cheapest first
await products.query({
  filter: { category: "electronics" },
  orderBy: { price: "ASC" },
});

// Sort by date, newest first
await articles.query({
  filter: { author: "john" },
  orderBy: { publishedAt: "DESC" },
});

// Sort by rating, highest first, which can be combined with LIMIT and OFFSET
await products.query({
  filter: { inStock: true },
  orderBy: { rating: "DESC" },
  limit: 5,
});
```
</Tab>

<Tab title="Python">
```python
# Sort by price, cheapest first
products.query(filter={"category": "electronics"}, order_by={"price": "ASC"})

# Sort by date, newest first
articles.query(filter={"author": "john"}, order_by={"publishedAt": "DESC"})

# Sort by rating, highest first
products.query(filter={"inStock": True}, order_by={"rating": "DESC"}, limit=5)
```
</Tab>

<Tab title="Redis CLI">
```bash
# Sort by price, cheapest first
SEARCH.QUERY products '{"category": "electronics"}' ORDERBY price ASC

# Sort by date, newest first
SEARCH.QUERY articles '{"author": "john"}' ORDERBY publishedAt DESC

# Sort by rating, highest first, which can be combined with LIMIT and OFFSET
SEARCH.QUERY products '{"inStock": true}' ORDERBY rating DESC LIMIT 5
```
</Tab>

</Tabs>

### 3. Controlling Output

By default, search results include document key, relevance score, and the contents of the document
(including the non-indexed fields).

For JSON and string indexes, that means the stored JSON objects as whole. For hash indexes, it means all fields and values.

<Tabs>

<Tab title="TypeScript">
```ts {3}
// Example: Return documents without content
await products.query({
  select: {},
  filter: { name: "headphones" },
});
```
</Tab>

<Tab title="Python">
```python
# Return documents without content
products.query(select={}, filter={"name": "headphones"})
```
</Tab>

<Tab title="Redis CLI">
```bash
# Return only keys and scores
SEARCH.QUERY products '{"name": "headphones"}' NOCONTENT
```
</Tab>

</Tabs>

<Tabs>

<Tab title="TypeScript">
```ts {3}
// Example: Return only `name` and `price`
await products.query({
  select: { name: true, price: true },
  filter: { name: "headphones" },
});
```
</Tab>

<Tab title="Python">
```python
# Return only `name` and `price`
products.query(select={"name": True, "price": True}, filter={"name": "headphones"})
```
</Tab>

<Tab title="Redis CLI">
```bash
# Return specific fields only
SEARCH.QUERY products '{"name": "headphones"}' SELECT 2 name price
```
</Tab>

</Tabs>

<Note>
When using [aliased fields](/docs/redis/search/schema-definition#aliased-fields),
use the **actual document field name** (not the alias) when selecting fields to return.
This is because aliasing happens at the index level and does not modify the underlying documents.
</Note>

***

### 4. Score Function

Score function lets you tweak the relevance scores of search results using numeric field values from your documents.
This is useful when you want to incorporate signals like popularity, recency, or price into the final ranking.

Only `.fast()` fields of type `i64`, `u64`, or `f64` can be used with score function.

#### Field Values

Each `FIELDVALUE` entry references a numeric field and optionally configures
how its value is transformed before being applied to the score:

* **`MODIFIER`** (default: `none`) — A mathematical transformation applied to the field value before use:

| Modifier     | Description                                          |
| ------------ | ---------------------------------------------------- |
| `none`       | Use the field value as-is, with no transformation.   |
| `log`        | Common logarithm (log base 10).                      |
| `log1p`      | Common logarithm of `1 + value`.                     |
| `log2p`      | Common logarithm of `2 + value`.                     |
| `ln`         | Natural logarithm (log base e).                      |
| `ln1p`       | Natural logarithm of `1 + value`.                    |
| `ln2p`       | Natural logarithm of `2 + value`.                    |
| `square`     | Square of the value (`value²`).                      |
| `sqrt`       | Square root of the value.                            |
| `reciprocal` | Reciprocal of the value (`1 / value`).               |

* **`FACTOR`** (default: `1.0`) — A float multiplier applied **after** the modifier transformation.
* **`MISSING`** (default: `0.0`) — A float fallback value used when:
  * The field value is missing from the document.
  * The field value is invalid for the chosen modifier (e.g., a negative value with `log`).

If both the field value and the missing value are invalid for the modifier, the final contribution is `MISSING * FACTOR`.

#### Combine Mode

When multiple `FIELDVALUE` entries are specified, `COMBINEMODE` controls how their results are combined:

* **`multiply`** (default) — Multiply all field value results together.
* **`sum`** — Add all field value results together.

#### Score Mode

`SCOREMODE` controls how the combined field value result is applied to the original query relevance score:

* **`multiply`** (default) — Multiply the original score by the combined result.
* **`sum`** — Add the combined result to the original score.
* **`replace`** — Replace the original score with the combined result entirely.

<Tabs>

<Tab title="TypeScript">
```ts
// Boost results by a popularity field
await products.query({
  filter: { name: "headphones" },
  scoreFunc: "popularity",
});

// Use log1p modifier to dampen high popularity values, with a factor of 2
await products.query({
  filter: { name: "headphones" },
  scoreFunc: {
    field: "popularity",
    modifier: "log1p",
    factor: 2.0,
  },
});

// Fallback to 1.0 when the field is missing or invalid
await products.query({
  filter: { name: "headphones" },
  scoreFunc: {
    field: "popularity",
    modifier: "log1p",
    missing: 1.0,
  },
});

// Combine two field values: boost by popularity and recency
await products.query({
  filter: { name: "headphones" },
  scoreFunc: {
    fields: [
      { field: "popularity", modifier: "log1p" },
      { field: "recencyScore", modifier: "sqrt" },
    ],
    combineMode: "sum",
  },
});

// Replace the original score entirely with the combined result
await products.query({
  filter: { name: "headphones" },
  scoreFunc: {
    field: "rating",
    scoreMode: "replace",
  },
});
```
</Tab>

<Tab title="Python">
```python
# Boost results by a popularity field
products.query(filter={"name": "headphones"}, score_func="popularity")

# Use log1p modifier to dampen high popularity values, with a factor of 2
products.query(
    filter={"name": "headphones"},
    score_func={"field": "popularity", "modifier": "log1p", "factor": 2.0},
)

# Fallback to 1.0 when the field is missing or invalid
products.query(
    filter={"name": "headphones"},
    score_func={"field": "popularity", "modifier": "log1p", "missing": 1.0},
)

# Combine two field values: boost by popularity and recency
products.query(
    filter={"name": "headphones"},
    score_func={
        "fields": [
            {"field": "popularity", "modifier": "log1p"},
            {"field": "recencyScore", "modifier": "sqrt"},
        ],
        "combineMode": "sum",
    },
)

# Replace the original score entirely with the combined result
products.query(
    filter={"name": "headphones"},
    score_func={"field": "rating", "scoreMode": "replace"},
)
```
</Tab>

<Tab title="Redis CLI">
```bash
# Boost results by a popularity field
SEARCH.QUERY products '{"name": "headphones"}' SCOREFUNC FIELDVALUE popularity

# Use log1p modifier to dampen high popularity values, with a factor of 2
SEARCH.QUERY products '{"name": "headphones"}' SCOREFUNC FIELDVALUE popularity MODIFIER log1p FACTOR 2.0

# Fallback to 1.0 when the field is missing or invalid
SEARCH.QUERY products '{"name": "headphones"}' SCOREFUNC FIELDVALUE popularity MODIFIER log1p MISSING 1.0

# Combine two field values: boost by popularity and recency
SEARCH.QUERY products '{"name": "headphones"}' SCOREFUNC COMBINEMODE sum FIELDVALUE popularity MODIFIER log1p FIELDVALUE recencyScore MODIFIER sqrt

# Replace the original score entirely with the combined result
SEARCH.QUERY products '{"name": "headphones"}' SCOREFUNC SCOREMODE replace FIELDVALUE rating
```
</Tab>

</Tabs>

<Warning>
`SCOREFUNC` cannot be used together with `ORDERBY`. Since `ORDERBY` overrides the relevance
score with the sort field's value, combining it with score function is not supported.
</Warning>

***

### 5. Highlighting

Highlighting allows you to see why a document matched the query by marking the matching portions of the document's fields.

By default, `<em>` and `</em>` are used as the highlight tags.

<Tabs>

<Tab title="TypeScript">
```ts
// Highlight matching terms
await products.query({
  filter: { description: "wireless noise cancelling" },
  highlight: { fields: ["description"] },
});

// Custom open and close highlight tags
await products.query({
  filter: { description: "wireless" },
  highlight: { fields: ["description"], preTag: "!!", postTag: "**" },
});
```
</Tab>

<Tab title="Python">
```python
# Highlight matching terms
products.query(
    filter={"description": "wireless noise cancelling"},
    highlight={"fields": ["description"]},
)

# Custom open and close highlight tags
products.query(
    filter={"description": "wireless"},
    highlight={"fields": ["description"], "preTag": "!!", "postTag": "**"},
)
```
</Tab>

<Tab title="Redis CLI">
```bash
# Highlight matching terms
SEARCH.QUERY products '{"description": "wireless noise cancelling"}' HIGHLIGHT FIELDS 1 description

# Custom open and close highlight tags
SEARCH.QUERY products '{"description": "wireless"}' HIGHLIGHT FIELDS 1 description TAGS !! **
```
</Tab>

</Tabs>

Note that highlighting only works for operators that resolve to terms, such as term or phrase queries.

<Note>
When using [aliased fields](/docs/redis/search/schema-definition#aliased-fields),
use the **alias name** (not the actual document field name) when specifying fields to highlight.
The highlighting feature works with indexed field names, which are the aliases.
</Note>

- [Blog Search](https://upstash.com/docs/redis/search/recipes/blog-search.md)
- [E-commerce Search](https://upstash.com/docs/redis/search/recipes/e-commerce-search.md)
- [Overview](https://upstash.com/docs/redis/search/recipes/overview.md)
- [User Directory](https://upstash.com/docs/redis/search/recipes/user-directory.md)

# Schemas
Source: https://upstash.com/docs/redis/search/schema-definition

Every search index requires a schema that defines the structure of searchable documents. The schema allows for type-safety and allows us to optimize your data for very fast queries.

We provide a schema builder utility called `s` that makes it easy to define a schema.

```ts
import { Redis, s } from "@upstash/redis"
```

### Field Type Reference

| SDK Method | Redis CLI Type | Description | Supports FAST | Range Operators | Text Operators |
|---|---|---|---|---|---|
| `s.string()` | `TEXT` | Full-text searchable field with tokenization and stemming | No | No | `$smart`, `$phrase`, `$fuzzy`, `$regex` |
| `s.keyword()` | `KEYWORD` | Exact-match string (no tokenization) | Yes | Yes (`$gt`, `$gte`, `$lt`, `$lte`) | No |
| `s.number()` | `F64` (default), `U64`, `I64` | Numeric field | Yes | Yes | No |
| `s.date()` | `DATE` | Date/time field | Yes | Yes | No |
| `s.boolean()` | `BOOL` | Boolean field | Yes | No | No |
| `s.facet()` | `FACET` | Hierarchical path-based field | No | No | No (only `$eq`, `$in`) |

<Note>
In the TypeScript SDK, `s.number()` defaults to `F64`. You can specify `s.number("U64")` or
`s.number("I64")` for unsigned or signed 64-bit integers. `F64` fields are FAST by default.
</Note>

### FAST Fields

The `FAST` flag creates a columnar store for a field, enabling:
* **Sorting** with `ORDERBY` in queries
* **Score functions** with `SCOREFUNC FIELDVALUE`
* **Metric aggregations** (`$avg`, `$sum`, `$min`, `$max`, `$count`, etc.)

In the TypeScript SDK, numeric (`F64`), boolean, and date fields are FAST **by default**. You can
disable it with `.fast(false)`. In Redis CLI, you must explicitly add the `FAST` keyword after the
field type.

```bash
# Redis CLI — FAST must be explicit
SEARCH.CREATE products ON JSON PREFIX 1 product: SCHEMA name TEXT price F64 FAST rating F64 FAST
```

If you attempt to use `ORDERBY`, `SCOREFUNC`, or metric aggregations on a non-FAST field, you will get an error.

***

### Basic Usage

The schema builder provides methods for each field type:

```ts
const schema = s.object({
  name: s.string(),
  age: s.number(),
  createdAt: s.date(),
  active: s.boolean(),
  tag: s.keyword(),
  category: s.facet(),
})
```

The schema builder also supports chaining field options. We'll see what `noTokenize()` and `noStem()` are used for in the section below.

```ts {2,3}
const schema = s.object({
  sku: s.string().noTokenize(),
  brand: s.string().noStem(),
  price: s.number(),
})
```

### Nested Objects

The schema builder supports nested object structures:

```ts
const schema = s.object({
  title: s.string(),
  author: s.object({
    name: s.string(),
    email: s.string(),
  }),
  stats: s.object({
    views: s.number(),
    likes: s.number(),
  }),
})
```

### Where to use the Schema

We need the schema when creating or querying an index:

```ts
import { Redis, s } from "@upstash/redis"

const redis = Redis.fromEnv()

const schema = s.object({
  name: s.string(),
  description: s.string(),
  category: s.string().noTokenize(),
  price: s.number("F64"),
  inStock: s.boolean(),
})

const products = await redis.search.createIndex({
  name: "products",
  dataType: "json",
  prefix: "product:",
  schema,
})
```

***

## Tokenization & Stemming

When you store text in a search index, it goes through two transformations: **Tokenization** and **Stemming**. By default, text fields are both tokenized and stemmed. Understanding these helps you configure fields correctly.

### Tokenization

Tokenization splits text into individual searchable words (tokens) by breaking on spaces and punctuation.

| Original Text        | Tokens                       |
| -------------------- | ---------------------------- |
| `"hello world"`      | `["hello", "world"]`         |
| `"user@example.com"` | `["user", "example", "com"]` |
| `"SKU-12345-BLK"`    | `["SKU", "12345", "BLK"]`    |

This is great for natural language because searching for "world" will match "hello world". But it breaks values that should stay together.

**When to disable tokenization** with `.noTokenize()`:

* Email addresses (`user@example.com`)
* URLs (`https://example.com/page`)
* Product codes and SKUs (`SKU-12345-BLK`)
* UUIDs (`550e8400-e29b-41d4-a716-446655440000`)
* Category slugs (`electronics/phones/android`)

```ts
const schema = s.object({
  title: s.string(),
  email: s.string().noTokenize(),
  sku: s.string().noTokenize(),
})
```

***

### Stemming

Stemming reduces words to their root form so different variations match the same search.

| Word                                   | Stemmed Form |
| -------------------------------------- | ------------ |
| `"running"`, `"runs"`, `"runner"`      | `"run"`      |
| `"studies"`, `"studying"`, `"studied"` | `"studi"`    |
| `"experiments"`, `"experimenting"`     | `"experi"`   |

This way, a user searching for "running shoes" will also find "run shoes" and "runner shoes".

**When to disable stemming** with `.noStem()`:

* Brand names (`Nike` shouldn't match `Nik`)
* Proper nouns and names (`Johnson` shouldn't become `John`)
* Technical terms (`React` shouldn't match `Reac`)
* When using regex patterns (stemmed text won't match your expected patterns)

```ts
const schema = s.object({
  description: s.string(),
  brand: s.string().noStem(),
  authorName: s.string().noStem(),
})
```

***

## Keyword Fields

The `KEYWORD` field type is for exact-match strings. Unlike `TEXT` fields, keywords are not tokenized or stemmed — the entire value is treated as a single token.

KEYWORD fields support numeric query operators (`$eq`, `$in`, `$gt`, `$gte`, `$lt`, `$lte`), which are not available on `TEXT` fields.

<Tabs>

<Tab title="TypeScript">
```ts
const schema = s.object({
  tag: s.keyword(),
})
```
</Tab>

<Tab title="Python">
```python
schema = {
    "tag": "KEYWORD",
}
```
</Tab>

<Tab title="Redis CLI">
```bash
SEARCH.CREATE idx ON JSON PREFIX 1 prefix: SCHEMA tag KEYWORD
```
</Tab>

</Tabs>

**When to use KEYWORD instead of TEXT:**

* When you need range operators (`$gt`, `$gte`, `$lt`, `$lte`) on string values
* When the entire string should be treated as a single unit (no word splitting)
* For tags, labels, status codes, or any string that should match exactly

***

## Facet Fields

The `FACET` field type is for hierarchical path-based faceted search. Values must be `/`-delimited paths starting with `/`.

FACET fields only support `$eq` and `$in` operators.
They are primarily used with the [`$facet` aggregation](/docs/redis/search/aggregation-operators/bucket-aggregations/facet)
to build category trees and faceted navigation.

<Tabs>

<Tab title="TypeScript">
```ts
const schema = s.object({
  category: s.facet(),
})
```
</Tab>

<Tab title="Python">
```python
schema = {
    "category": "FACET",
}
```
</Tab>

<Tab title="Redis CLI">
```bash
SEARCH.CREATE idx ON JSON PREFIX 1 prefix: SCHEMA category FACET
```
</Tab>

</Tabs>

**Example — querying facet fields:**

<Tabs>

<Tab title="TypeScript">
```ts
await index.query({
  filter: { category: { $eq: "/category/books/fiction" } },
});

await index.query({
  filter: {
    category: { $in: ["/category/books", "/category/electronics"] },
  },
});
```
</Tab>

<Tab title="Python">
```python
index.query(filter={"category": {"$eq": "/category/books/fiction"}})

index.query(filter={"category": {"$in": ["/category/books", "/category/electronics"]}})
```
</Tab>

<Tab title="Redis CLI">
```bash
SEARCH.QUERY products '{"category": {"$eq": "/category/books/fiction"}}'

SEARCH.QUERY products '{"category": {"$in": ["/category/books", "/category/electronics"]}}'
```
</Tab>

</Tabs>

***

## Aliased Fields

Aliased fields allow you to index the same document field multiple times with different settings,
or to create shorter names for complex nested paths.
Use the `FROM` keyword to specify which document field the alias points to.

<Tabs>

<Tab title="TypeScript">
```ts
import { Redis, s } from "@upstash/redis";

const redis = Redis.fromEnv();

const products = await redis.search.createIndex({
  name: "products",
  dataType: "json",
  prefix: "product:",
  schema: s.object({
    description: s.string(),
    descriptionExact: s.string().noStem().from("description"),
    authorName: s.string().from("metadata.author.displayName"),
  }),
});
```

</Tab>

<Tab title="Python">
```python
from upstash_redis import Redis

redis = Redis.from_env()

products = redis.search.create_index(
    name="products",
    data_type="json",
    prefix="product:",
    schema={
        "description": "TEXT",
        "descriptionExact": {"type": "TEXT", "nostem": True, "from": "description"},
        "authorName": {"type": "TEXT", "from": "metadata.author.displayName"},
    },
)
```

</Tab>

<Tab title="Redis CLI">
```bash
# Index 'description' twice with different settings
# Create a short alias for a deeply nested field
SEARCH.CREATE products ON JSON PREFIX 1 product: SCHEMA description TEXT descriptionExact TEXT FROM description NOSTEM authorName TEXT FROM metadata.author.displayName
```

</Tab>

</Tabs>

Common use cases for aliased fields:

* **Same field with different settings**: Index a text field both with and without stemming. Use the stemmed version for general searches and the non-stemmed version for exact matching or regex queries.
* **Shorter query paths**: Create concise aliases for deeply nested fields like `metadata.author.displayName` to simplify queries.

<Note>
When using aliased fields:
* Use the **alias name** in queries and highlighting (e.g., `descriptionExact`, `authorName`)
* Use the **actual field name** when selecting fields to return (e.g., `description`, `metadata.author.displayName`)

This is because aliasing happens at the index level and does not modify the underlying documents.

</Note>

***

## Non-Indexed Fields

Documents don't need to match the schema exactly:

* **Extra fields**: Fields in your document that aren't defined in the schema are simply ignored. They won't be indexed or searchable.
* **Missing fields**: If a document is missing a field defined in the schema, that document won't appear in search results that filter on the missing field.

***

## Schema Examples

**E-commerce product schema**

<Tabs>

```ts
import { Redis, s } from "@upstash/redis"

const redis = Redis.fromEnv()

const products = await redis.search.createIndex({
  name: "products",
  dataType: "hash",
  prefix: "product:",
  schema: s.object({
    name: s.string(),
    sku: s.string().noTokenize(), // Exact-match SKU codes
    brand: s.string().noStem(), // Brand names without stemming
    description: s.string(),
    price: s.number("F64"), // Sortable (F64) price
    rating: s.number("F64"), // Sortable (F64) rating
    reviewCount: s.number("U64"),  // Non-sortable (U64) review count
    inStock: s.boolean(),
  }),
})
```

</Tab>

<Tab title="Python">
```python
from upstash_redis import Redis

redis = Redis.from_env()

products = redis.search.create_index(
    name="products",
    data_type="hash",
    prefix="product:",
    schema={
        "name": "TEXT",
        "sku": {"type": "TEXT", "notokenize": True},
        "brand": {"type": "TEXT", "nostem": True},
        "description": "TEXT",
        "price": "F64",
        "rating": "F64",
        "reviewCount": "U64",
        "inStock": "BOOL",
    },
)
```

</Tab>

<Tab title="Redis CLI">
```bash
SEARCH.CREATE products ON HASH PREFIX 1 product: SCHEMA name TEXT sku TEXT NOTOKENIZE brand TEXT NOSTEM description TEXT price F64 FAST rating F64 FAST reviewCount U64 inStock BOOL FAST
```
</Tab>

</Tabs>

**User directory schema**

<Tabs>

<Tab title="TypeScript">
```ts
import { Redis, s } from "@upstash/redis";

const redis = Redis.fromEnv();

const users = await redis.search.createIndex({
  name: "users",
  dataType: "json",
  prefix: "user:",
  schema: s.object({
    username: s.string().noTokenize(),
    profile: s.object({
      displayName: s.string().noStem(),
      bio: s.string(),
      email: s.string().noTokenize(),
    }),
    createdAt: s.date().fast(),
    verified: s.boolean(),
  }),
});
```

</Tab>

<Tab title="Python">
```python
from upstash_redis import Redis

redis = Redis.from_env()

users = redis.search.create_index(
    name="users",
    data_type="json",
    prefix="user:",
    schema={
        "username": {"type": "TEXT", "notokenize": True},
        "profile.displayName": {"type": "TEXT", "nostem": True},
        "profile.bio": "TEXT",
        "profile.email": {"type": "TEXT", "notokenize": True},
        "createdAt": {"type": "DATE", "fast": True},
        "verified": "BOOL",
    },
)
```

</Tab>

<Tab title="Redis CLI">
```bash
SEARCH.CREATE users ON JSON PREFIX 1 users: SCHEMA username TEXT NOTOKENIZE profile.displayName TEXT NOSTEM profile.bio TEXT contact.email TEXT NOTOKENIZE createdAt DATE FAST verified BOOL
```
</Tab>

</Tabs>

# Troubleshooting
Source: https://upstash.com/docs/redis/search/troubleshooting

Common errors and how to resolve them when working with Upstash Redis Search.

## Index Errors

### `ERR Index <name> already exists`

You tried to create an index that already exists.

**Fix:** Use the `existsOk` option (SDK) or `EXISTSOK` flag (CLI) to skip creation if an identical index already exists:

```bash
SEARCH.CREATE products ON JSON PREFIX 1 product: EXISTSOK SCHEMA name TEXT
```

Or drop the existing index first with `SEARCH.DROP <name>`.

If the existing index has a different schema/configuration, `EXISTSOK` still returns an error. In that case, drop and recreate the index (or use a different index name).

***

## Query Errors

### `ERR limit should be a positive number less than 1000`

The `LIMIT` value must be a positive integer. Valid range is `1` to `1000` (inclusive).

**Common causes:**
* Using `LIMIT 0` — the minimum is 1
* Using `LIMIT 1001` or greater — the maximum is 1000
* Using RediSearch-style `LIMIT <offset> <count>` syntax — Upstash uses separate `LIMIT` and `OFFSET` keywords

**Fix:**
```bash
# Correct
SEARCH.QUERY products '{}' LIMIT 10 OFFSET 20

# Incorrect (RediSearch style)
SEARCH.QUERY products '{}' LIMIT 20 10
```

### `ERR Unknown field operator: $not`

There is no `$not` operator. Use `$mustNot` for exclusion filtering:

```bash
# Correct
SEARCH.QUERY products '{"$mustNot": [{"status": "discontinued"}]}'

# Incorrect
SEARCH.QUERY products '{"status": {"$not": "discontinued"}}'
```

***

## Aggregation Errors

### Aggregation operator requires field to be FAST

```
Aggregation '<name>' operator '$avg' requires field '<field>' to be FAST
```

All metric aggregation operators (`$avg`, `$sum`, `$min`, `$max`, `$count`, `$cardinality`, `$stats`, `$extendedStats`, `$percentiles`) require the target field to be defined as `FAST` in the index schema.

**Fix:** Recreate the index with the field marked as `FAST`:

```bash
# Ensure 'price' has the FAST flag
SEARCH.CREATE products ON JSON PREFIX 1 product: SCHEMA name TEXT price F64 FAST
```

In the TypeScript SDK, numeric fields (`s.number("F64")`) and date fields (`s.date()`) are FAST by default. Boolean fields (`s.boolean()`) are also FAST by default. If you explicitly called `.fast(false)`, remove it.

### Missing required 'field' property

```
Aggregation '<name>' is missing required 'field' property
```

Every metric aggregation operator requires a `field` property pointing to the field to aggregate.

**Fix:** Pass `field` as an object property, not a bare string:

Correct:
```json
{"avg_price": {"$avg": {"field": "price"}}}
```

Incorrect — operator value is a bare string instead of an object:
```json
{"avg_price": {"$avg": "price"}}
```

### Aggregation must be a JSON object

```
Aggregation '<name>' must be a JSON object
```

The aggregation alias must map to an object containing an operator key (like `$avg`), not directly to a string or number.

**Fix:**

Correct:
```json
{"avg_price": {"$avg": {"field": "price"}}}
```

Incorrect — alias maps directly to an operator string:
```json
{"avg_price": "$avg"}
```

***

## Schema Errors

### Field type mismatches

If a document field's value doesn't match the schema type (e.g., a string value `"abc"` for a numeric field), that document is silently skipped during indexing for that field. It will not appear in queries that filter on the mismatched field.

### Missing document fields

If a document doesn't have a field defined in the schema, it simply won't match queries filtering on that field. No error is raised.

***

## Upstash Redis Search vs RediSearch

Upstash Redis Search uses `SEARCH.*` commands and is a separate implementation from the
open-source RediSearch module which uses `FT.*` commands. The two are **not** compatible.

| | Upstash Redis Search | RediSearch |
|---|---|---|
| Command prefix | `SEARCH.*` | `FT.*` |
| Engine | Tantivy (Rust) | RediSearch (C) |
| Query syntax | JSON-based filters | RediSearch query syntax |
| Pagination | `LIMIT <count> OFFSET <offset>` (separate keywords) | `LIMIT <offset> <count>` (combined) |
| Hosting | Serverless (Upstash) | Self-hosted or Redis Cloud |

If you are migrating from RediSearch, you will need to rewrite your queries to use the JSON filter syntax and `SEARCH.*` commands.

# 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.

<Note>
  This solution may have a latency overhead (about 4 ms). See [the blog
  post](https://blog.upstash.com/serverless-database-connections) for more.
</Note>

```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

Please reach out to us via support@upstash.com if above does not help.

<Info>
  See [the blog post](https://blog.upstash.com/serverless-database-connections)
  about the database connections in serverless functions.
</Info>

# 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/upgrade-database) 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 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 `10MB` 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 a higher plan, or apply a custom quota increase if you are on Pay-as-You-Go plan. Please reach out to support@upstash.com about the options with higher max request size limit.

<Note>
  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.
</Note>

# 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/upgrade-database) 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.

# Connecting with Read-Only Access
Source: https://upstash.com/docs/redis/troubleshooting/readonly_connection

### Symptom

You are trying to connect to your Upstash Redis database using a read-only token via a TCP client (such as `redis-cli`, `ioredis`, or `redis-py`), but you receive an authentication error similar to:

```
WRONGPASS invalid username-password pair or user is disabled
```

### Diagnosis

When you enable the **Read-Only Token** toggle in the [Upstash Console](https://console.upstash.com), the TCP connection strings update the username from `default` to `default_ro`. This change can be easy to miss.

If you copied the read-only password but are still connecting with the `default` username (or omitting the username entirely), authentication will fail because the read-only password is associated with the `default_ro` user.

### Solution 1: Use the `default_ro` Username

The simplest approach is to use the built-in `default_ro` user. When you enable the **Read-Only Token** in the console, the connection strings automatically switch to use this user.

Make sure your connection includes both the `default_ro` username **and** the read-only password:

**redis-cli:**

```bash
redis-cli --tls -u rediss://default_ro:READ_ONLY_PASSWORD@YOUR_ENDPOINT:YOUR_PORT
```

**Node.js (ioredis):**

```javascript
const Redis = require("ioredis");

const client = new Redis("rediss://default_ro:READ_ONLY_PASSWORD@YOUR_ENDPOINT:YOUR_PORT");
```

**Python (redis-py):**

```python
import redis

r = redis.Redis(
    host="YOUR_ENDPOINT",
    port=YOUR_PORT,
    username="default_ro",
    password="READ_ONLY_PASSWORD",
    ssl=True,
)
```

<Tip>
  The easiest way to get the correct connection string is to enable the **Read-Only Token** toggle in the console and copy the connection string directly. The username and password will be pre-filled for you.
</Tip>

### Solution 2: Create a Custom Read-Only ACL User

If you need more control over permissions, you can create a custom user with read-only access using [Redis ACL](https://redis.io/docs/latest/operate/oss_and_stack/management/security/acl/).

**1. Connect with your admin credentials:**

```bash
redis-cli --tls -u rediss://default:YOUR_PASSWORD@YOUR_ENDPOINT:YOUR_PORT
```

**2. Create a read-only user:**

```
ACL SETUSER myreadonlyuser on >somesecurepassword ~* &* +@read -@dangerous
```

This command:
* `on` — enables the user
* `>somesecurepassword` — sets the password
* `~*` — allows access to all keys
* `&*` — allows access to all pub/sub channels
* `+@read` — grants all read commands
* `-@dangerous` — revokes dangerous commands (such as `KEYS`, `SCAN`)

You can further restrict key access by replacing `~*` with a pattern like `~cache:*` to only allow reading keys that match that prefix.

**3. Connect with the new user:**

```bash
redis-cli --tls -u rediss://myreadonlyuser:somesecurepassword@YOUR_ENDPOINT:YOUR_PORT
```

If you want to use the REST API with your custom ACL user, you can generate a REST token for it. See [REST Token for ACL Users](/docs/redis/features/restapi#rest-token-for-acl-users) for details.

# 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.

- [Agent Memory with Redis Search](https://upstash.com/docs/redis/tutorials/agent_memory.md): Build short-term and long-term memory for AI agents on Upstash Redis. Store working memory with TTLs and recall long-term memories with Redis Search full-text queries.
- [Deploy a Serverless API with AWS CDK and AWS Lambda](https://upstash.com/docs/redis/tutorials/api_with_cdk.md)
- [Autocomplete API with Serverless Redis](https://upstash.com/docs/redis/tutorials/auto_complete_with_serverless_redis.md)
- [Build Stateful Applications with AWS App Runner and Serverless Redis](https://upstash.com/docs/redis/tutorials/aws_app_runner_with_redis.md): This tutorial shows how to create a serverless and stateful application using AWS App Runner and Redis
- [Session Management on Google Cloud Run with Serverless Redis](https://upstash.com/docs/redis/tutorials/cloud_run_sessions.md): This tutorial shows how to manage user sessions on Google Cloud Run using Serverless Redis.
- [Cloudflare Workers with Websockets and Redis](https://upstash.com/docs/redis/tutorials/cloudflare_websockets_redis.md)
- [Use Redis in Cloudflare Workers](https://upstash.com/docs/redis/tutorials/cloudflare_workers_with_redis.md)
- [Backendless Coin Price List with GraphQL API, Serverless Redis and Next.JS](https://upstash.com/docs/redis/tutorials/coin_price_list.md)
- [Build a Leaderboard API At Edge using Cloudflare Workers and Redis](https://upstash.com/docs/redis/tutorials/edge_leaderboard.md): This tutorial shows how to build a Leaderboard API At Edge using Cloudflare Workers and Redis.
- [Express Session with Serverless Redis](https://upstash.com/docs/redis/tutorials/express_session.md): This tutorial shows how to use Upstash as the session storage of your Express application.
- [Serverless Golang API with Redis](https://upstash.com/docs/redis/tutorials/goapi.md)
- [Build a Serverless Histogram API with Redis](https://upstash.com/docs/redis/tutorials/histogram.md): This tutorial shows how to build a histogram API with Redis.
- [Job Processing and Event Queue with Serverless Redis](https://upstash.com/docs/redis/tutorials/job_processing.md): This tutorial shows how to use Upstash Redis for job/task processing.
- [Caching in Laravel with Redis](https://upstash.com/docs/redis/tutorials/laravel_caching.md)
- [Next.js with Redis](https://upstash.com/docs/redis/tutorials/nextjs_with_redis.md)
- [Building a Serverless Notification API for Your Web Application with Redis](https://upstash.com/docs/redis/tutorials/notification.md): This tutorial shows how to create a Serverless Notification API for Your Web Application with Redis.
- [Nuxt with Redis](https://upstash.com/docs/redis/tutorials/nuxtjs_with_redis.md): This tutorial shows how to use Upstash inside your Nuxt application.
- [Redis as a Cache for Your FastAPI App](https://upstash.com/docs/redis/tutorials/python_fastapi_caching.md)
- [Multithreaded Web Scraping with Redis Caching](https://upstash.com/docs/redis/tutorials/python_multithreading.md)
- [Rate Limiting for Your FastAPI App](https://upstash.com/docs/redis/tutorials/python_rate_limiting.md)
- [Build a Real-Time Chat Application with Serverless Redis](https://upstash.com/docs/redis/tutorials/python_realtime_chat.md)
- [Manage Sessions in Python with Serverless Redis](https://upstash.com/docs/redis/tutorials/python_session.md)
- [Building a URL Shortener with Redis](https://upstash.com/docs/redis/tutorials/python_url_shortener.md)
- [Serverless Python API with Redis](https://upstash.com/docs/redis/tutorials/pythonapi.md)
- [AWS Lambda Rate Limiting with Serverless Redis](https://upstash.com/docs/redis/tutorials/rate-limiting.md)
- [Redis Queue: From FIFO Lists to a Job Queue](https://upstash.com/docs/redis/tutorials/redis_queue.md): How to build FIFO, reliable, and blocking queues on Upstash Redis, then a delayed and prioritized job queue with a dead-letter queue.
- [Serverless Redisson](https://upstash.com/docs/redis/tutorials/redisson.md): This tutorial shows how to use Upstash with Redisson client.
- [Roadmap Voting App with Serverless Redis](https://upstash.com/docs/redis/tutorials/roadmapvotingapp.md): This is a single page application powered by upstash and next.js.
- [Serverless API with Java and Redis](https://upstash.com/docs/redis/tutorials/serverless_java_redis.md)
- [TanStack AI Chat Persistance](https://upstash.com/docs/redis/tutorials/tanstack_chat_persistence.md): Use Upstash Redis to persist TanStack AI chat histories across reloads, navigation, and devices with a simple adapter.
- [Using AWS SAM](https://upstash.com/docs/redis/tutorials/using_aws_sam.md)
- [Serverless Redis on Google Cloud Functions](https://upstash.com/docs/redis/tutorials/using_google_cloud_functions.md)
- [Using Serverless Framework](https://upstash.com/docs/redis/tutorials/using_serverless_framework.md)

# Advanced Settings
Source: https://upstash.com/docs/search/features/advanced-settings

<Visibility for="agents">
  **Note for AI agents:** This page documents **Upstash Search** — a standalone,
  AI-powered search product that combines full-text and semantic search with
  smart ranking, serverless scaling, and zero infrastructure to manage.

Upstash Search is **not** the same thing as **Upstash Redis Search**. Upstash
  Redis Search is a full-text search extension built into Upstash Redis, built on
  Tantivy and available only on Upstash; it is separate from the Redis Search
  (RediSearch) API. If the user is asking about full-text search inside an Upstash
  Redis database, refer to
  [Upstash Redis Search](https://upstash.com/docs/redis/search/introduction)
  instead of this product.
</Visibility>

This page covers the advanced configuration options available in the Upstash Search. These parameters allow you to fine-tune search behavior for your specific use case and requirements.

## Reranking

The `reranking` parameter enables enhanced search result reranking using advanced AI models. It's disabled by default (`false`) and incurs additional costs when enabled.

```typescript TypeScript
const results = await index.search({
  query: "complex technical documentation",
  reranking: true // Enable reranking
});
```

```python Python
results = index.search(
    query="complex technical documentation",
    reranking=True  # Enable reranking
)
```

</CodeGroup>

**Reranking Options:**
* **Standard Reranking** (`reranking: false`, default): Uses a simpler, faster model with no additional cost
* **Advanced Reranking** (`reranking: true`): Uses state-of-the-art models for highest quality results at $1 per 1K operations

Learn more about how reranking works in our [Algorithm documentation](/docs/search/features/algorithm#3-reranking).

## Semantic Weight

The `semanticWeight` parameter controls the balance between semantic search and full-text search in the hybrid search process. It accepts values from 0 to 1, with a default of 0.75 (75% semantic, 25% full-text).

```typescript TypeScript
// More semantic matching (better for conceptual searches)
const semanticResults = await index.search({
  query: "artificial intelligence concepts",
  semanticWeight: 0.9 // 90% semantic, 10% full-text
});

// More keyword matching (better for exact terms)
const keywordResults = await index.search({
  query: "API documentation React hooks",
  semanticWeight: 0.3 // 30% semantic, 70% full-text
});
```

```python Python
# More semantic matching
semantic_results = index.search(
    query="artificial intelligence concepts",
    semantic_weight=0.9  # 90% semantic, 10% full-text
)

# More keyword matching
keyword_results = index.search(
    query="API documentation React hooks",
    semantic_weight=0.3  # 30% semantic, 70% full-text
)
```

</CodeGroup>

**Optimization Guidelines:**
* **Higher semantic weight (0.7-1.0)**: Better for conceptual searches, finding related content, and handling synonyms
* **Lower semantic weight (0.0-0.4)**: Better for exact keyword matching, technical queries, and specific terms

Read more about hybrid search in our [Algorithm documentation](/docs/search/features/algorithm#2-hybrid-vector-search).

## Input Enrichment

The `inputEnrichment` parameter controls whether queries are enhanced using AI before searching. It's enabled by default (`true`) and significantly improves search quality at the cost of some additional latency.

```typescript TypeScript
// Disable input enrichment for faster responses
const results = await index.search({
  query: "space opera",
  inputEnrichment: false // Faster but less enhanced results
});

// Default behavior (enrichment enabled)
const enrichedResults = await index.search({
  query: "space opera"
  // inputEnrichment: true is the default
});
```

```python Python
# Disable input enrichment for faster responses
results = index.search(
    query="space opera",
    input_enrichment=False  # Faster but less enhanced results
)

# Default behavior (enrichment enabled)
enriched_results = index.search(
    query="space opera"
    # input_enrichment=True is the default
)
```

</CodeGroup>

**When to Disable Input Enrichment:**
* When you need the fastest possible response times
* When you want to preserve the exact user query for full-text search

**Benefits of Input Enrichment:**
* Handles typos and alternative phrasings
* Expands queries with related terms and context
* Improves understanding of user intent
* Adds semantic context to ambiguous queries

Learn more about input enrichment in our [Algorithm documentation](/docs/search/features/algorithm#1-input-enrichment).

## Keep Original Query After Enrichment

The `keepOriginalQueryAfterEnrichment` parameter controls whether the original user query is preserved alongside the AI-enriched version during search. It's disabled by default (`false`) and only has an effect when `inputEnrichment` is enabled.

```typescript TypeScript
// Keep both original and enriched queries
const results = await index.search({
  query: "space opera",
  keepOriginalQueryAfterEnrichment: true // Uses both original and enriched
});
```

</CodeGroup>

**When to Enable This Option:**
* When you want to ensure exact keyword matches are included
* When the original query contains specific technical terms or identifiers
* When you want to balance AI enhancement with literal query matching

<Note>
This parameter has no effect when `inputEnrichment` is set to `false`, since there's no enriched query to compare against.
</Note>

## Filter

The `filter` parameter allows you to restrict search results based on content criteria. It accepts either a string expression (SQL-like syntax) or a structured filter object (TypeScript SDK only).

```typescript TypeScript
// String filter expression (SQL-like syntax)
const results = await index.search({
  query: "wireless headphones",
  filter: "category = 'Electronics' AND in_stock > 0"
});

// TypeSafe structured filter (TypeScript SDK only)
const results2 = await index.search({
  query: "wireless headphones",
  filter: {
    AND: [
      { category: { equals: 'Electronics' } },
      { in_stock: { greaterThan: 0 } }
    ]
  }
});
```

```python Python
# String filter expression (SQL-like syntax)
results = index.search(
    query="wireless headphones",
    filter="category = 'Electronics' AND in_stock > 0"
)
```

</CodeGroup>

For detailed information about filter syntax, operators, and examples, see the [Filtering documentation](/docs/search/features/filtering).

## Example: Complete Configuration

Here's an example showing all parameters configured together:

```typescript TypeScript
const results = await index.search({
  query: "machine learning algorithms for data analysis",
  limit: 15,
  filter: "category = 'data-science' AND difficulty_level <= 'intermediate'",
  reranking: true,
  semanticWeight: 0.8,
  inputEnrichment: true
});
```

```python Python
results = index.search(
    query="machine learning algorithms for data analysis",
    limit=15,
    filter="category = 'data-science' AND difficulty_level <= 'intermediate'",
    reranking=True,
    semantic_weight=0.8,
    input_enrichment=True
)
```

</CodeGroup>

This configuration:
* Searches for ML content with enhanced query processing
* Returns up to 15 results
* Filters for data science content at beginner to intermediate levels
* Uses premium reranking for best quality results
* Emphasizes semantic matching (80%) over keyword matching (20%)
* Enables input enrichment for better intent understanding

# Algorithm
Source: https://upstash.com/docs/search/features/algorithm

Our algorithm combines AI-powered query enhancement, hybrid search techniques, and intelligent reranking to understand user intent (also known as [search intent](https://backlinko.com/hub/seo/search-intent)) and return the most accurate results.

Upstash Search processes every query through three key stages:
1. **Input Enrichment**: Enhances the search query using AI to better understand user intent.
2. **Hybrid Vector Search**: Combines semantic search and full-text search to find relevant documents.
3. **Reranking**: Uses AI models to reorder results based on relevance.

### 1. Input Enrichment

The first stage enhances your search query using a Large Language Model (LLM). This process:

* Expands the original query with related terms and context
* Improves understanding of user intent
* Handles typos and alternative phrasings
* Adds semantic context that might be missing from the original query

While input enrichment introduces some latency, it significantly improves search quality.

Input enrichment is enabled by default. You can disable this feature if you want to preserve the user query for full text-search or if you want to reduce latency.

```typescript TypeScript
const results = await index.search({
  query: "space opera",
  inputEnrichment: false // faster but less enhanced results
});
```

```python Python
results = index.search(
    query="space opera",
    input_enrichment=False  # faster but less enhanced results
)
```

</CodeGroup>

### 2. Hybrid Vector Search

The second stage performs hybrid search by combining semantic search and full-text search:

* **Semantic Search**: Uses vector embeddings to understand meaning and context
* **Full-Text Search**: Performs traditional keyword matching
* **Result Combination**: Merges results using configurable weights

By default, Upstash Search uses a 75% semantic weight and 25% full-text weight. You can adjust this balance based on your use case:

* Higher semantic weight: Better for conceptual searches and finding related content
* Lower semantic weight: Better for exact keyword matching and technical queries

```typescript TypeScript
const results = await index.search({
  query: "artificial intelligence concepts",
  semanticWeight: 0.9 // 90% semantic, 10% full-text
});
```

```python Python
results = index.search(
    query="artificial intelligence concepts",
    semantic_weight=0.9  # 90% semantic, 10% full-text
)
```

</CodeGroup>

### 3. Reranking

The final stage reranks the hybrid search results using AI models. Upstash Search offers two reranking options:

**Advanced Reranking (`reranking: true`)**
* Uses a powerful, state-of-the-art reranking model
* Provides the highest quality results
* Costs $1 per 1K reranking operations
* Recommended for applications where search quality is critical

**Standard Reranking (`reranking: false`, default)**
* Uses a simpler, faster reranking model
* Still provides significant improvements over raw hybrid results
* No additional cost

```typescript TypeScript
const results = await index.search({
  query: "complex technical documentation",
  reranking: true // uses premium reranking model
});
```

```python Python
results = index.search(
    query="complex technical documentation",
    reranking=True  # uses premium reranking model
)
```

</CodeGroup>

## Conclusion

This three-stage approach ensures that Upstash Search:

* **Understands Intent**: Input enrichment helps the system understand what users are really looking for
* **Finds Relevant Content**: Hybrid search captures both semantic meaning and exact keyword matches
* **Prioritizes Quality**: Reranking ensures the most relevant results appear first
* **Stays Flexible**: Each stage can be configured based on your specific needs

The result is a search system that works well across all kinds of content and domains, handling everything from precise technical queries to broad conceptual searches.

# Content and Metadata
Source: https://upstash.com/docs/search/features/content-and-metadata

***

## 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

<Tabs>

<Tab title="Python">
```py
index.upsert(
  documents=[
    {
      "id": "star-wars",
      "content": { "text": "Star Wars is a sci-fi space opera."}
    }
  ]
)
```
</Tab>

<Tab title="TypeScript">
```ts
await index.upsert([
  {
    id: "star-wars",
    content: { title: "Star Wars", genre: "sci-fi", category: "classic" }
  }
]);
```
</Tab>

</Tabs>

***

## 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

<Tabs>

<Tab title="Python">
```py
index.upsert(
  documents=[
    {
      "id": "star-wars",
      "content": { "text": "Star Wars is a sci-fi space opera."},
      "metadata": {
        "genre": "sci-fi",
      }
    }
  ]
)
```
</Tab>

<Tab title="TypeScript">
```ts
await index.upsert([
  {
    id: "star-wars",
    content: { title: "Star Wars", genre: "sci-fi", category: "classic" },
    metadata: { director: "George Lucas" } ,
  }
]);
```
</Tab>

</Tabs>

***

## 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 or metadata matching with the filter.

Upstash Search allows you to filter by content and metadata 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 and metadata keys and boolean operators
to combine them.

To distinguish fields in content and metadata, metadata keys must be prefixed with
the `@metadata` identifier.

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, but filterable
  metadata: {
    sku: "AT-WH-001",
    supplier_id: "SUP-123",
  }
}
```

Filter documents like so:

<Tabs>
<Tab title="Python">
```py
scores = index.search(
    query="sony headphones",
    filter="warehouse_location = 'A3-15' AND @metadata.supplier_id = 'SUP-123'",
)
```
</Tab>
<Tab title="TypeScript">
```ts
const searchResults = await index.search({
    query: "sony headphones",
    filter: "warehouse_location = 'A3-15' AND @metadata.supplier_id = 'SUP-123'",
});
```
</Tab>
</Tabs>

### TypeSafe Filters (TypeScript)

In our [TypeScript SDK](https://github.com/upstash/search-js), we support a typesafe way to build filters:

```ts
import { Search } from "@upstash/search";

type Content = { text: string }
type Metadata = { count: number }

const client = Search.fromEnv()
const searchIndex = client.index<Content, Metadata>("hello world!");

const results = await searchIndex.search({
  query: "hello world!",
  limit: 2,
  filter: {
    AND: [
      // filtering by content field
      { text: { glob: "*test-data*" } },
      // filtering by metadata field (add @metadata prefix)
      { "@metadata.count": { greaterThanOrEquals: 3 } }
    ],
  },
});
```

<Note>
  You can pass type parameters to the `index` method to enable type-safe filters. The first type parameter is for [content fields](/docs/search/features/content-and-metadata#content), and the optional second type parameter is for [metadata fields](/docs/search/features/content-and-metadata).

Use the `@metadata` prefix to filter by metadata fields in your filter objects. If you don't need to filter by metadata, you can omit the metadata type parameter.
</Note>

You can use the `AND` and `OR` operators to build complex filters.

```ts AND
const searchResults = await index.search({
  query: "sony headphones",
  filter: {
    AND: [
      { warehouse_location: { equals: 'A3-15' } },
      { in_stock: { greaterThan: 0 } }
    ]
  },
});
```

```ts OR
const searchResults = await index.search({
  query: "sony headphones",
  filter: {
    OR: [
      { warehouse_location: { equals: 'A3-15' } },
      { in_stock: { greaterThan: 0 } }
    ]
  },
});
```

```ts Nested AND/OR
const searchResults = await index.search({
  query: "sony headphones",
  filter: {
    AND: [
      { category: { contains: 'electronics' } },
      { OR: [
        { warehouse_location: { equals: 'A3-15' } },
        { in_stock: { greaterThan: 0 } }
      ]}
    ]
  },
});
```

</CodeGroup>

All the operations below except for filtering array elements and nested objects are supported in the typesafe filters.

***

## 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.

<Tabs>

<Tab title="Python">
```python
index = client.index("foo")
index.upsert( ... )
```
</Tab>

<Tab title="TypeScript">
```ts
const index = client.index("movies");
await index.upsert( ... );
```
</Tab>

</Tabs>

***

## Listing Indexes

Names of all the active indexes of a database can be listed as follows:

<Tabs>

<Tab title="Python">
```python
client.list_indexes()
```
</Tab>

<Tab title="TypeScript">
```ts
await client.listIndexes()
```
</Tab>

</Tabs>

***

## Deleting an Index

Leftover indexes can be deleted as follows:

<Tabs>

<Tab title="Python">
```python
client.delete_index("foo")
```
</Tab>

<Tab title="TypeScript">
```ts
await client.index("foo").deleteIndex();
```
</Tab>

</Tabs>

# 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.

<Tabs>

<Tab title="Python">
```python
scores = index.search(
    query="space opera",
    limit=2,
    reranking=True,
)
```
</Tab>

<Tab title="TypeScript">
```ts
const searchResults = await index.search({
  query: "space opera",
  limit: 2,
  reranking: true,
});
```
</Tab>

</Tabs>

# FAQ
Source: https://upstash.com/docs/search/help/faq

***

## 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.

# Docusaurus Integration
Source: https://upstash.com/docs/search/integrations/docusaurus

## Features

* 🤖 AI-powered search results based on your documentation
* 🎨 Modern and responsive UI
* 🌜 Dark/Light mode support

## Installation

To install the package, run:

```bash
npm install @upstash/docusaurus-theme-upstash-search
```

## Configuration

### Enabling the Searchbar

To enable the searchbar, add the following to your docusaurus config file:

```js
export default {
  themes: ['@upstash/docusaurus-theme-upstash-search'],
  // ...
  themeConfig: {
    // ...
    upstash: {
      upstashSearchRestUrl: "UPSTASH_SEARCH_REST_URL",
      upstashSearchReadOnlyRestToken: "UPSTASH_SEARCH_READ_ONLY_REST_TOKEN",
      upstashSearchIndexName: "UPSTASH_SEARCH_INDEX_NAME",
    },
  },
};
```

The default index name is `docusaurus`. You can override it by setting the `upstashSearchIndexName` option.

You can fetch your URL and read only token from [Upstash Console](https://console.upstash.com/search). **Make sure to use the read only token!**

If you do not have a search database yet, you can create one from [Upstash Console](https://console.upstash.com/search). Make sure to use Upstash generated embedding model.

## Indexing Your Documentation

### Setting Up Environment Variables

To index your documentation, create a `.env` file with the following environment variables:

```bash
UPSTASH_SEARCH_REST_URL=
UPSTASH_SEARCH_REST_TOKEN=
UPSTASH_SEARCH_INDEX_NAME=
DOCS_PATH=
```

You can fetch your URL and token from [Upstash Console](https://console.upstash.com/search). This time **do not use the read only token** since we are upserting data.

### Running the Indexing Script

After setting up your environment variables, run the indexing command:

```bash
npx index-docs-upstash
```

### Configuration Options

* **DOCS_PATH**: The indexing script looks for documentation in the `docs` directory by default. You can specify a different path using the `DOCS_PATH` option.
* **UPSTASH_SEARCH_INDEX_NAME**: The default index name is `docusaurus`. You can override it by setting the `UPSTASH_SEARCH_INDEX_NAME` option. Make sure the name you set while indexing matches with your themeConfig `upstashSearchIndexName` option.

For more details on how this integration works, check out [the official repository](https://github.com/upstash/docusaurus-theme-upstash-search).

# Getting Started
Source: https://upstash.com/docs/search/overall/getstarted

***

***

We now have **[Redis Search](/docs/redis/search/introduction)** in Upstash.

If you are starting a new project, we recommend using **Redis Search**:

* Index and query your Redis data with a schema.
* Use advanced query operators and aggregations.
* Keep your data and search in one place.

See [Redis Search Introduction](/docs/redis/search/introduction) for details.
</Tip>

***

## Quickstart

Check out our Next.js quickstart guide if you're working in Next.js.

<CardGroup cols={1}>
  <Card title="Next.js" icon="node-js" href="/search/tutorials/nextjs">
    Use Upstash Search in your Next.js app
  </Card>
</CardGroup>

***

## Create a Database

Create a Search Database by navigating to the `Vector` tab and clicking on the `Search Database` button under `Create`.

<img />

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:

<img />

***

## 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`:

<img />

A dialog with the following options will open:

<img />

* **Index:** An [index](/docs/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](/docs/search/features/content-and-metadata).

***

### 2. Add Documents via SDKs

<Tabs>

```python
from upstash_search import Search

client = Search(
    url="<UPSTASH_SEARCH_REST_URL>",
    token="<UPSTASH_SEARCH_REST_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",
            },
        },
    ],
)
```

</Tab>

```ts
import { Search } from "@upstash/search"

const client = new Search({
  url: "<SEARCH_INDEX_REST_URL>",
  token: "<SEARCH_INDEX_REST_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" },
  },
])
```

</Tab>

</Tabs>

***

## 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`:

<img />

### 2. Searching Data via SDKs

<Tabs>

<Tab title="Python">
```py
scores = index.search( query="space opera", limit=2, )
```
</Tab>

<Tab title="TypeScript">
```ts
const searchResults = await index.search({
  query: "space opera",
  limit: 2,
  reranking: true,
});
```
</Tab>

</Tabs>

***

**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

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.

<Note>
Looking for full-text search inside an Upstash Redis database instead? See [Upstash Redis Search](/docs/redis/search/introduction), a full-text search extension built into Upstash Redis. Upstash Search (this page) is a standalone product that combines full-text and semantic search.
</Note>

***

## 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](/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](/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](/docs/search/overall/getstarted)!

- [Delete](https://upstash.com/docs/search/sdks/py/commands/delete.md)
- [Fetch](https://upstash.com/docs/search/sdks/py/commands/fetch.md)
- [Info](https://upstash.com/docs/search/sdks/py/commands/info.md)
- [Range](https://upstash.com/docs/search/sdks/py/commands/range.md)
- [Reset](https://upstash.com/docs/search/sdks/py/commands/reset.md)
- [Search](https://upstash.com/docs/search/sdks/py/commands/search.md)
- [Upsert](https://upstash.com/docs/search/sdks/py/commands/upsert.md)

# 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](/docs/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="<SEARCH_INDEX_REST_URL>",
    token="<SEARCH_INDEX_REST_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")

## Telemetry

This sdk sends anonymous telemetry data to help us improve your experience.
We collect the following:

* SDK version
* Platform (Cloudflare, AWS or Vercel)
* Runtime version (python@vX)

You can opt out using the allow_telemetry flag when creating the client:

```ts
client = Search(
    url="UPSTASH_SEARCH_REST_URL",
    token="UPSTASH_SEARCH_REST_TOKEN",
    allow_telemetry=False,
)
```

- [Delete](https://upstash.com/docs/search/sdks/ts/commands/delete.md)
- [Fetch](https://upstash.com/docs/search/sdks/ts/commands/fetch.md)
- [Info](https://upstash.com/docs/search/sdks/ts/commands/info.md)
- [Range](https://upstash.com/docs/search/sdks/ts/commands/range.md)
- [Reset](https://upstash.com/docs/search/sdks/ts/commands/reset.md)
- [Search](https://upstash.com/docs/search/sdks/ts/commands/search.md)
- [Upsert](https://upstash.com/docs/search/sdks/ts/commands/upsert.md)

# 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

<CodeGroup>
```bash npm
npm install @upstash/search
```

```bash yarn
yarn add @upstash/search
```

```bash pnpm
pnpm add @upstash/search
```

```bash bun
bun install @upstash/search
```

</CodeGroup>

***

## 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](/docs/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: "<SEARCH_INDEX_REST_URL>",
  token: "<SEARCH_INDEX_REST_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<Content, Metadata>("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<Content>({
  id: "id",
  content: { title: "Movie title", ... }
});
```

## Telemetry

This sdk sends anonymous telemetry data to help us improve your experience.
We collect the following:

* SDK version
* Platform (Cloudflare, AWS or Vercel)
* Runtime version (node@18.x)

You can opt out by setting the `UPSTASH_DISABLE_TELEMETRY` environment variable
to any truthy value.

```sh
UPSTASH_DISABLE_TELEMETRY=1
```

Alternatively, you can disable telemetry programmatically:

```ts
const index = client.index("movies", {
  enableTelemetry: false,
});
```

# Database Migrator
Source: https://upstash.com/docs/search/tools/databasemigrator

## Introduction

This tool helps you to migrate your data from other service providers (e.g. Algolia, Meilisearch)
to your Upstash Search Database.

### Migrate Using npx
The command below prompts you to provide credentials for the indexes that you want to do the migration between.

```sh
npx @upstash/search-migrator
```

### Using Flags

You can also provide your credentials and other information as command-line flags.
Here are some examples:

#### Algolia to Upstash

```sh
npx @upstash/search-migrator \
  --upstash-url "UPSTASH_SEARCH_REST_URL" \
  --upstash-token "UPSTASH_SEARCH_REST_TOKEN" \
  --algolia-app-id "YOUR_ALGOLIA_APP_ID" \
  --algolia-api-key "YOUR_ALGOLIA_WRITE_API_KEY"
```

#### Meilisearch to Upstash

```sh
npx @upstash/search-migrator \
  --upstash-url "UPSTASH_SEARCH_REST_URL" \
  --upstash-token "UPSTASH_SEARCH_REST_TOKEN" \
  --meilisearch-host "YOUR_MEILISEARCH_HOST" \
  --meilisearch-api-key "YOUR_MEILISEARCH_API_KEY"
```

## Obtaining Credentials

### Upstash

1. Go to your [Upstash Console](https://console.upstash.com/).
2. Select your Search Database.
3. Under the **Details** section, you will find your `UPSTASH_SEARCH_REST_URL` and `UPSTASH_SEARCH_REST_TOKEN`.
   * `--upstash-url` corresponds to `UPSTASH_SEARCH_REST_URL`.
   * `--upstash-token` corresponds to `UPSTASH_SEARCH_REST_TOKEN`.

* You may want to check out
[@upstash/search-migrator](https://www.npmjs.com/package/@upstash/search-migrator)
to see how to find credentials for other service providers

## Migration Process

The migrator will:

1. **Connect** to your source database (Algolia or Meilisearch)
2. **Fetch** all documents from the specified index
3. **Transform** the data to match Upstash Search's format
4. **Upload** the documents to your Upstash Search database
5. **Verify** the migration by comparing document counts

### Data Transformation

The migrator automatically handles the transformation of your data:

* **Document IDs**: Preserved from the source
* **Content**: Mapped to Upstash Search's content field
* **Metadata**: Preserved as metadata in Upstash Search
* **Searchable fields**: All fields become searchable by default

<Note>
  For free tier, 10000 documents can be upserted daily,
  so a database migration with more than 10000 entries could
  be interrupted.
</Note>

### Getting Help

If you encounter any issues during migration:

1. Check the error messages for specific details
2. Verify your credentials are correct
3. Ensure your source database is accessible
4. Contact support at [support@upstash.com](mailto:support@upstash.com)

## Final Remarks
If you've come to this point without any issues, congratulations! you may resume your work
with upstash search, an advanced, developer frinedly search product.

For further insights, please visit [@upstash/search-migrator](https://www.npmjs.com/package/@upstash/search-migrator)

# Documentation Crawler
Source: https://upstash.com/docs/search/tools/documentationcrawler

## Introduction

This tool helps you crawl documentation websites incrementally, extract their content, and create a search index in Upstash Search.

## Usage

It is available both as a CLI tool and a library.

### CLI Usage

You can run the CLI directly using `npx` (no installation required):

```sh
npx @upstash/search-crawler
```

Or with command-line options:

```sh
npx @upstash/search-crawler \
  --upstash-url "UPSTASH_SEARCH_REST_URL" \
  --upstash-token "UPSTASH_SEARCH_REST_TOKEN" \
  --index-name "my-index" \
  --doc-url "https://example.com/docs"
```

You will be prompted for any missing options:

* Your Upstash Search URL
* Your Upstash Search token
* (Optional) Custom index name
* The documentation URL to crawl

#### What the Tool Does

1. **Discover** all internal documentation links
2. **Crawl** each page and extract content
3. **Track** new or obsolete data
4. **Upsert** the new records into your Upstash Search index

### Library Usage

You can also use this as a library in your own code:

```typescript
import {
  crawlAndIndex,
  type CrawlerOptions,
  type CrawlerResult,
} from "@upstash/search-crawler";

const options: CrawlerOptions = {
  upstashUrl: "UPSTASH_SEARCH_REST_URL",
  upstashToken: "UPSTASH_SEARCH_REST_TOKEN",
  indexName: "my-docs",
  docUrl: "https://example.com/docs",
  silent: true, // no console output
};

const result: CrawlerResult = await crawlAndIndex(options);
```

## Obtaining Upstash Credentials

1. Go to your [Upstash Console](https://console.upstash.com/).
2. Select your Search index. (See [How to Create Search Index](/docs/search/overall/getstarted#create-a-database))
3. Under the **Details** section, copy your `UPSTASH_SEARCH_REST_URL` and `UPSTASH_SEARCH_REST_TOKEN`.
   * `--upstash-url` corresponds to `UPSTASH_SEARCH_REST_URL`
   * `--upstash-token` corresponds to `UPSTASH_SEARCH_REST_TOKEN`

## Further Reading

Try combining this tool with [Qstash Schedule](/docs/qstash/features/schedules) to keep your database up to date with docs. You may deploy your crawler on a server and call it on a schedule regularly to fetch updates in your docs. Check out our example project for implementation details: [A modern documentation library to search and track the docs.](https://github.com/upstash/search-js/tree/main/examples/search-docs)

For further insights, see [@upstash/search-crawler](https://github.com/upstash/search-crawler)

# Docs Search Quickstart
Source: https://upstash.com/docs/search/tutorials/buildsearchbar

***

## Introduction

Upstash Search makes it easy to add a fast, ready-to-use search bar to
your docs site, no complex setup needed. In this tutorial, you’ll learn
how to quickly integrate a modern search experience that helps your users
find what they need. With just a few tweaks, you can use this solution in
any project and deliver great search lightning fast.

***

### 1. Project Setup

First, create an Upstash Search Database
if you don't already have one ([Getting Started guide](/docs/search/overall/getstarted))
and then create a new Next.js application and install the related packages:

```shell
npx create-next-app@latest search-docs-app
cd search-docs-app
npm install @upstash/search @upstash/search-ui lucide-react
```

***

### 2. Add Environment Variables

Find the environment variables from your database dashboard and add them to your `.env` file:

```bash
NEXT_PUBLIC_UPSTASH_SEARCH_URL=<YOUR_SEARCH_REST_URL>
NEXT_PUBLIC_UPSTASH_SEARCH_READONLY_TOKEN=<YOUR_SEARCH_READONLY_TOKEN>
```

***

### 3. Create the Component

Create the [search component](https://github.com/upstash/search-ui) in `app/components/search-bar.tsx`:

```typescript title="app/components/search-bar.tsx"
"use client"

import { SearchBar } from "@upstash/search-ui"
import "@upstash/search-ui/dist/index.css"
import { Search } from "@upstash/search"
import { FileText } from "lucide-react"

const client = new Search({
  url: process.env.NEXT_PUBLIC_UPSTASH_SEARCH_URL! ,
  token: process.env.NEXT_PUBLIC_UPSTASH_SEARCH_READONLY_TOKEN!,
})
// 👇 your search index name
const index = client.index<{ title: string }>("default")

export default function SearchComponent() {
  return (
    <div className="max-w-sm mt-24 mx-auto">
      <SearchBar.Dialog>
        <SearchBar.DialogTrigger placeholder="Search..." />

<SearchBar.DialogContent>
          <SearchBar.Input placeholder="Type to search..." />
          <SearchBar.Results
            searchFn={(query) => {
              // 👇 100% type-safe: whatever you return here is
              // automatically typed as `result` below
              return index.search({ query, limit: 10, reranking: true })
            }}
          >
            {(result) => (
                <div key={result.id} onClick={() => {
                   window.open(result.metadata?.url as string, "_blank")
                 }}>
               <SearchBar.Result
                 value={result.id}
                 className="cursor-pointer hover:bg-gray-50 transition-colors duration-200"
               >
                <SearchBar.ResultIcon>
                    <FileText className="text-gray-600" />
                </SearchBar.ResultIcon>

<SearchBar.ResultContent>
                  <SearchBar.ResultTitle>
                    {result.content.title}
                  </SearchBar.ResultTitle>
                  <p className="text-xs text-gray-500 mt-0.5">Docs</p>
                </SearchBar.ResultContent>
              </SearchBar.Result>
              </div>
            )}
          </SearchBar.Results>
        </SearchBar.DialogContent>
      </SearchBar.Dialog>
    </div>
  )
}
```

***

### 4. Crawl Docs to Feed the Component

Call [`npx @upstash/search-crawler`](https://github.com/upstash/search-crawler)
in your command line and follow the CLI, you will be prompted to provide:

* Upstash Search URL (as set in your environment variables)
* Upstash Search Rest Token (as set in your environment variables)
* Upstash Search Index Name (Go for `default` for convenience)
* Docs URL to crawl (Let's go for `https://upstash.com/docs`)
<Note>
  If you prefer not to choose `default` index name,
  don't forget to update the line in the `SearchComponent`
  where you provide the index name.
</Note>

***

### 5. Prepare the UI

Replace the following code snippet with the code in `app/page.tsx`:

```typescript title="app/page.tsx"
import SearchComponent from "./components/search-bar";

export default function Home() {
  return (
    <div className="min-h-screen bg-gradient-to-br from-blue-50 via-white to-indigo-50">
      <main className="flex-1">
        <div className="max-w-4xl mx-auto px-4 sm:px-6 lg:px-8 pt-20 pb-16">
          <div className="text-center mb-12">
            <h2 className="text-4xl md:text-5xl font-bold text-gray-900 mb-6">
              Search Upstash Documentation
            </h2>
            <p className="text-xl text-gray-600 max-w-2xl mx-auto leading-relaxed">
              Find exactly what you're looking for in our comprehensive documentation.
              Search through guides, APIs, tutorials, and more with lightning-fast results.
            </p>
          </div>
          {/* Search Component */}
          <div className="max-w-2xl mx-auto">
            <SearchComponent />
          </div>
          <div className="mt-20 grid md:grid-cols-3 gap-8">
            <div className="text-center">
              <div className="w-12 h-12 bg-blue-100 rounded-lg flex items-center justify-center mx-auto mb-4">
                <svg className="w-6 h-6 text-blue-600" fill="none" stroke="currentColor" viewBox="0 0 24 24" aria-hidden="true">
                  <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2}
                    d="M13 10V3L4 14h7v7l9-11h-7z" />
                </svg>
              </div>
              <h3 className="text-lg font-semibold text-gray-900 mb-2">Lightning Fast</h3>
              <p className="text-gray-600">Get instant search results powered by advanced indexing</p>
            </div>
            <div className="text-center">
              <div className="w-12 h-12 bg-green-100 rounded-lg flex items-center justify-center mx-auto mb-4">
                <svg className="w-6 h-6 text-green-600" fill="none" stroke="currentColor" viewBox="0 0 24 24">
                  <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2}
                    d="M9 12l2 2 4-4m6 2a9 9 0 11-18 0 9 9 0 0118 0z" />
                </svg>
              </div>
              <h3 className="text-lg font-semibold text-gray-900 mb-2">Accurate Results</h3>
              <p className="text-gray-600">Reranking ensures the most relevant content appears first</p>
            </div>
            <div className="text-center">
              <div className="w-12 h-12 bg-purple-100 rounded-lg flex items-center justify-center mx-auto mb-4">
                <svg className="w-6 h-6 text-purple-600" fill="none" stroke="currentColor" viewBox="0 0 24 24">
                  <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2}
                    d="M12 6.253v13m0-13C10.832 5.477 9.246 5 7.5 5S4.168 5.477 3 6.253v13C4.168
                  18.477 5.754 18 7.5 18s3.332.477 4.5 1.253m0-13C13.168 5.477 14.754 5 16.5
                  5c1.746 0 3.332.477 4.5 1.253v13C19.832 18.477 18.246 18 16.5 18c-1.746
                  0-3.332.477-4.5 1.253" />
                </svg>
              </div>
              <h3 className="text-lg font-semibold text-gray-900 mb-2">Comprehensive</h3>
              <p className="text-gray-600">Search across all documentation, guides, and API references</p>
            </div>
          </div>
        </div>
      </main>
    </div>
  );
}

```

***

### 6. Start the Project

Run the following command to start the development server:

```bash
npm run dev
```

Open your browser and navigate to `http://localhost:3000` to test the application.

You can search through Upstash docs, and results will redirect you to the page you are looking for.

***

### Next Steps

Learn more about:

* [Typescript SDK](/docs/search/sdks/ts/getting-started)
* [Docusaurus Integration](/docs/search/integrations/docusaurus)

# Next.js Search Quickstart
Source: https://upstash.com/docs/search/tutorials/nextjs

***

### 1. Create a Search Database

Follow the instructions in the [Getting Started guide](/docs/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=<YOUR_SEARCH_REST_URL>
UPSTASH_SEARCH_REST_TOKEN=<YOUR_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<string, unknown>;
  metadata: Record<string, unknown>;
  score: number;
}

export default function Home() {
  const [searchResults, setSearchResults] = useState<SearchResult[]>([]);
  const [query, setQuery] = useState("");
  const [isUpserting, setIsUpserting] = useState(false);
  const [upsertSuccess, setUpsertSuccess] = useState(false);

const upsertData = async () => {
    setIsUpserting(true);
    setUpsertSuccess(false);
    await fetch("/api/upsert", { method: "POST" });
    setIsUpserting(false);
    setUpsertSuccess(true);
  };

return (
    <main className="min-h-screen bg-emerald-50 flex flex-col items-center py-10">
      <div className="w-full max-w-2xl bg-white shadow-md rounded-lg p-6">
        <header className="mb-6 text-center">
          <h1 className="text-2xl font-bold text-emerald-800">Search App</h1>
          <p className="text-emerald-600">
            Upsert data and search through the database.
          </p>
        </header>

<div className="mb-6">
          <button
            onClick={upsertData}
            disabled={isUpserting}
            className={`w-full py-2 px-4 rounded-md text-white ${
              isUpserting
                ? "bg-emerald-300"
                : "bg-emerald-500 hover:bg-emerald-600"
            }`}
          >
            {isUpserting ? "Upserting..." : "Upsert Data"}
          </button>
          {upsertSuccess && (
            <p className="mt-2 text-sm text-emerald-600">
              Data upserted successfully!
            </p>
          )}
        </div>

<div className="mb-6">
          <div className="flex gap-2">
            <input
              type="text"
              value={query}
              onChange={(e) => setQuery(e.target.value)}
              placeholder="Search..."
              className="flex-1 border border-emerald-300 rounded-md px-4 py-2 text-gray-800 focus:outline-none focus:ring-2 focus:ring-emerald-500"
            />
            <button
              onClick={search}
              className="bg-emerald-500 text-white px-4 py-2 rounded-md hover:bg-emerald-600"
            >
              Search
            </button>
          </div>
        </div>

<ul className="space-y-2">
          {searchResults.map((result, index) => (
            <li
              key={index}
              className="bg-emerald-100 p-4 rounded-md shadow-sm text-emerald-800"
            >
              <p className="font-bold">ID: {result.id}</p>
              <p className="text-sm">Content: {JSON.stringify(result.content)}</p>
              <p className="text-sm">Metadata: {JSON.stringify(result.metadata)}</p>
              <p className="text-sm">Score: {result.score}</p>
            </li>
          ))}
        </ul>
      </div>
    </main>
  );
}
```

***

### 7. Start the Project

Run the following command to start the development server:

```bash
npm run dev
```

Open your browser and navigate to `http://localhost:3000` to test the application.

You can click the `Upsert Data` button to add three movies to your database and use the search bar to make a query.

***

### Next Steps

Learn more about:

* [Typescript SDK](/docs/search/sdks/ts/getting-started)
* [Content and Metadata fields](/docs/search/features/content-and-metadata)

# SearchBar
Source: https://upstash.com/docs/search/ui/search-bar

***

## 1. Installation

```bash
npm install @upstash/search-ui
```

```typescript
// 👇 import package and optimized styles
import { SearchBar } from "@upstash/search-ui"
import "@upstash/search-ui/dist/index.css"
```

***

## 2. Code Example

Our search component is designed to be **provider agnostic**.

In the code below we're using [Upstash Search](/docs/search/overall/whatisupstashsearch) - our solution for fast, reliable and highly scalable serverless search.

Creating a search database takes less than a minute: [get started here](/docs/search/overall/getstarted). To follow along with Upstash Search, install the package:

```bash
npm install @upstash/search
```

```tsx
"use client"

import { SearchBar } from "@upstash/search-ui"
import "@upstash/search-ui/dist/index.css"

import { Search } from "@upstash/search"
import { FileText } from "lucide-react"

const client = new Search({
  url: "<UPSTASH_SEARCH_URL>",
  token: "<YOUR_SEARCH_READONLY_TOKEN>",
})

// 👇 your search index name
const index = client.index<{ title: string }>("movies")

export default function Page() {
  return (
    <div className="max-w-sm mt-24 mx-auto">
      <SearchBar.Dialog>
        <SearchBar.DialogTrigger placeholder="Search movies..." />

<SearchBar.DialogContent>
          <SearchBar.Input placeholder="Type to search movies..." />
          <SearchBar.Results
            searchFn={(query) => {
              // 👇 100% type-safe: whatever you return here is
              // automatically typed as `result` below
              return index.search({ query, limit: 10, reranking: true })
            }}
          >
            {(result) => (
              <SearchBar.Result value={result.id} key={result.id}>
                <SearchBar.ResultIcon>
                  <FileText className="text-gray-600" />
                </SearchBar.ResultIcon>

<SearchBar.ResultContent>
                  <SearchBar.ResultTitle>
                    {result.content.title}
                  </SearchBar.ResultTitle>
                  <p className="text-xs text-gray-500 mt-0.5">Movie</p>
                </SearchBar.ResultContent>
              </SearchBar.Result>
            )}
          </SearchBar.Results>
        </SearchBar.DialogContent>
      </SearchBar.Dialog>
    </div>
  )
}
```

***

## Using a Readonly Token (recommended)

The token used in the `Search` client above is a read-only token.

<img />

This token is safe to expose on the frontend. This allows your application to perform search queries without the need for a backend API.

To use environment variables for the token, set it as `NEXT_PUBLIC_YOUR_READONLY_TOKEN` in your `.env` file.

Optionally, you can also create a separate backend API to handle search on the server.

***

## Handling Results

You can perform actions with the search results by using the `onSelect` prop on `SearchBar.Item`:

```tsx
<SearchBar.Result
  onSelect={() => {
    // 👇 do something with result
    console.log(result)
  }}
  value={result.id}
  key={result.id}
>
```

***

## Customization

This component is beautifully pre-styled, but 100% customizable. You can change every piece of it yourself by passing normal React props to each component (such as `className`).

**For example**: If you wanted to change the primary color, change the CSS classes:

```tsx
<SearchBar.Input
  className="focus:ring-red-500"
  placeholder="Type to search movies..."
/>

<SearchBar.ResultTitle
  className="font-medium text-gray-900"
  highlightClassName="decoration-red-500 text-red-500"
>
  {result.content.title}
</SearchBar.ResultTitle>
```

***

This component is based on the [Radix UI Dialog Primitive](https://www.radix-ui.com/primitives/docs/components/dialog) and Paco Coursey's [cmdk](https://cmdk.paco.me/) library.

# Delete Vectors
Source: https://upstash.com/docs/vector/api/endpoints/delete

You can delete one or more vectors by providing their vector ids,
vector id prefix, or metadata filter.

<Tip>
  Vectors will be deleted from the default namespace by default.
  You can use a different namespace by specifying it in the request path.
</Tip>

## Request

<ParamField body="ids" type="string[]">
  Array of vector ids to delete.
</ParamField>

<ParamField body="prefix" type="string">
  Prefix of vector ids to delete.
</ParamField>

<ParamField body="filter" type="string">
  [Metadata filter](/docs/vector/features/filtering) for the vectors to delete.
  <Warning>Deleting vectors with metadata filter is a O(N) operation that performs a full scan.
  Therefore, it might be slow for large indexes.</Warning>
</ParamField>

## Path

<ParamField path="namespace" type="string" default="">
  The namespace to use.
  When no namespace is specified, the default namespace will be used.
</ParamField>

## Response

<ResponseField name="deleted" type="number">
  The number of the successfully deleted vectors.
</ResponseField>

```sh curl
curl $UPSTASH_VECTOR_REST_URL/delete \
  -X DELETE \
  -H "Authorization: Bearer $UPSTASH_VECTOR_REST_TOKEN" \
  -d '{ "ids": [ "id-0", "id-1" ] }'
```

```sh curl (Namespace)
curl $UPSTASH_VECTOR_REST_URL/delete/ns \
  -X DELETE \
  -H "Authorization: Bearer $UPSTASH_VECTOR_REST_TOKEN" \
  -d '{ "ids": [ "id-0", "id-1" ] }'
```

</RequestExample>

```json 200 OK
{
    "result": {
        "deleted": 2
    }
}
```

</ResponseExample>

# Delete Namespace
Source: https://upstash.com/docs/vector/api/endpoints/delete-namespace

<Note>
  The default namespace, which is the empty string `""`, cannot be deleted.
</Note>

## Request

This endpoint doesn't require any additional data.

## Path

<ParamField path="namespace" type="string" required>
  The namespace to delete.
</ParamField>

## Response

<ResponseField name="result" type="string">
  `"Success"` string.
</ResponseField>

```sh curl
curl $UPSTASH_VECTOR_REST_URL/delete-namespace/ns \
  -X DELETE \
  -H "Authorization: Bearer $UPSTASH_VECTOR_REST_TOKEN"
```

</RequestExample>

```json 200 OK
{
    "result": "Success"
}
```

```json 404 Not Found
{
    "error": "Namespace ns for the index $NAME does not exist",
    "status": 404
}
```

</ResponseExample>

# Fetch Vectors
Source: https://upstash.com/docs/vector/api/endpoints/fetch

You can fetch vector values or metadata of one or more by providing
their vector ids or id prefix.

<Tip>
  Vectors will be fetched from the default namespace by default.
  You can use a different namespace by specifying it in the request path.
</Tip>

## Request

<ParamField body="ids" type="string[]">
  Array of vector ids to fetch.
</ParamField>

<ParamField body="prefix" type="string">
  Prefix of vector ids to fetch.

<Info>When you fetch vectors with an id prefix, at most `1000` vectors will be returned.
  If there are more vectors, please use the [range](./range) API with an id prefix.</Info>
</ParamField>

<ParamField body="includeMetadata" type="boolean" default="false">
  Whether to include the metadata of the vectors in the response, if any.
  It is recommended to set this to `true` to easily identify vectors.
</ParamField>
<ParamField body="includeVectors" type="boolean" default="false">
  Whether to include the vector values in the response.
  It is recommended to set this to `false` as the vector values can be
  quite big, and not needed most of the time.
</ParamField>
<ParamField body="includeData" type="boolean" default="false">
  Whether to include the data of the vectors in the response, if any.
</ParamField>

## Path

<ParamField path="namespace" type="string" default="">
  The namespace to use.
  When no namespace is specified, the default namespace will be used.
</ParamField>

## Response

<ResponseField name="Vectors" type="Object[]">
  Array of vectors in the same order they provided in the ids array.
  Array elements can be `null` if no such vector exists with the provided id.
  <Expandable defaultOpen="true">
    <ResponseField name="id" type="string" required>
      The id of the vector.
    </ResponseField>
    <ResponseField name="vector" type="number[]">
      The dense vector value for dense and hybrid indexes.
    </ResponseField>
    <ResponseField name="sparseVector" type="Object[]">
      The sparse vector value for sparse and hybrid indexes.
      <Expandable defaultOpen="true">
        <ResponseField name="indices" type="number[]">
          Indices of the non-zero valued dimensions.
        </ResponseField>
        <ResponseField name="values" type="number[]">
          Values of the non-zero valued dimensions.
        </ResponseField>
      </Expandable>
    </ResponseField>
    <ResponseField name="metadata" type="Object">
      The metadata of the vector, if any.
    </ResponseField>
    <ResponseField name="data" type="string">
      The unstructured data of the vector, if any.
    </ResponseField>
  </Expandable>
</ResponseField>

```sh curl
curl $UPSTASH_VECTOR_REST_URL/fetch \
  -H "Authorization: Bearer $UPSTASH_VECTOR_REST_TOKEN" \
  -d '{ "ids": ["id-0"], "includeMetadata": true }'
```

```sh curl (Namespace)
curl $UPSTASH_VECTOR_REST_URL/fetch/ns \
  -H "Authorization: Bearer $UPSTASH_VECTOR_REST_TOKEN" \
  -d '{ "ids": ["id-0", "id-1"], "includeMetadata": true }'
```

</RequestExample>

```json 200 OK
{
    "result": [
        {
            "id": "id-0",
            "metadata": {
                "link": "upstash.com"
            }
        },
        {
            "id": "id-1"
        }
    ]
}
```

</ResponseExample>

# Fetch Random Vector
Source: https://upstash.com/docs/vector/api/endpoints/fetch-random

## Request

This endpoint doesn't require any additional data.

## Path

<ParamField path="namespace" type="string" default="">
  The namespace to use.
  When no namespace is specified, the default namespace will be used.
</ParamField>

## Response

The response will be `null` if the namespace is empty.

<ResponseField name="id" type="string" required>
  The id of the vector.
</ResponseField>
<ResponseField name="vector" type="number[]">
  The dense vector value for dense and hybrid indexes.
</ResponseField>
<ResponseField name="sparseVector" type="Object[]">
  The sparse vector value for sparse and hybrid indexes.
  <Expandable defaultOpen="true">
    <ResponseField name="indices" type="number[]">
      Indices of the non-zero valued dimensions.
    </ResponseField>
    <ResponseField name="values" type="number[]">
      Values of the non-zero valued dimensions.
    </ResponseField>
  </Expandable>
</ResponseField>

```sh curl
curl $UPSTASH_VECTOR_REST_URL/random \
  -H "Authorization: Bearer $UPSTASH_VECTOR_REST_TOKEN"
```

```sh curl (Namespace)
curl $UPSTASH_VECTOR_REST_URL/random/ns \
  -H "Authorization: Bearer $UPSTASH_VECTOR_REST_TOKEN"
```

</RequestExample>

```json 200 OK
{
    "result": {
        "id": "id-0",
        "vector": [0.1, 0.2]
    }
}
```

</ResponseExample>

# Index Info
Source: https://upstash.com/docs/vector/api/endpoints/info

Info will be updated eventually, so it might take some time to see the effect of changes in this endpoint.

## Request

This request doesn't require any additional data.

## Response

<ResponseField name="vectorCount" type="number" required>
  The number of vectors in the index, that are ready to use. This is the total
  number of vectors across all namespaces.
</ResponseField>
<ResponseField name="pendingVectorCount" type="number" required>
  The number of vectors in the index, that are still processing and not ready to
  use. This is the total number of pending vectors across all namespaces.
</ResponseField>
<ResponseField name="indexSize" type="number" required>
  The total size of the index, in **bytes**.
</ResponseField>
<ResponseField name="dimension" type="number" required>
  Dimension of the vectors.
</ResponseField>
<ResponseField name="similarityFunction" type="string" required>
  Name of the similarity function used in indexing and queries.
</ResponseField>

<ResponseField name="indexType" type="string" required>
  Type of the index. Possible values: `"DENSE"`, `"SPARSE"`, `"HYBRID"`
</ResponseField>

<ResponseField name="denseIndex" type="object">
  Information about the dense vector index configuration.
  <Expandable>
    <ResponseField name="dimension" type="number" required>
      Dimension of the dense vectors.
    </ResponseField>
    <ResponseField name="similarityFunction" type="string" required>
      Similarity function used for dense vector comparisons.
      Possible values: `"COSINE"`, `"EUCLIDEAN"`, `"DOT_PRODUCT"`
    </ResponseField>
    <ResponseField name="embeddingModel" type="string" required>
      Name of the embedding model used for dense vectors.
    </ResponseField>
  </Expandable>
</ResponseField>
<ResponseField name="sparseIndex" type="object">
  Information about the sparse vector index configuration.
  <Expandable>
    <ResponseField name="embeddingModel" type="string" required>
      Name of the embedding model used for sparse vectors.
    </ResponseField>
  </Expandable>
</ResponseField>
<ResponseField name="namespaces" type="object" required>
  Map of namespace names to namespace .

<Note>Every index has at least one namespace called default namespace, whose name is the empty string `""`.</Note>
  <Expandable defaultOpen="true">
    <ResponseField name="vectorCount" type="number" required>
      The number of vectors in the namespace, that are ready to use.
    </ResponseField>
    <ResponseField name="pendingVectorCount" type="number" required>
      The number of vectors in the namespace, that are still processing
      and not ready to use.
    </ResponseField>
  </Expandable>
</ResponseField>

```sh curl
curl $UPSTASH_VECTOR_REST_URL/info \
  -H "Authorization: Bearer $UPSTASH_VECTOR_REST_TOKEN"
```

</RequestExample>

```json 200 OK
{
  "result": {
    "vectorCount": 7,
    "pendingVectorCount": 0,
    "indexSize": 43501,
    "dimension": 1024,
    "similarityFunction": "COSINE",
    "indexType": "HYBRID",
    "denseIndex": {
      "dimension": 1024,
      "similarityFunction": "COSINE",
      "embeddingModel": "BGE_M3"
    },
    "sparseIndex": {
      "embeddingModel": "BM25"
    },
    "namespaces": {
      "": {
        "vectorCount": 6,
        "pendingVectorCount": 0
      },
      "ns": {
        "vectorCount": 1,
        "pendingVectorCount": 0
      }
    }
  }
}
```

</ResponseExample>

# List Namespaces
Source: https://upstash.com/docs/vector/api/endpoints/list-namespaces

## Request

This endpoint doesn't require any additional data.

## Response

<ResponseField name="namespaces" type="string[]" required>
  Array of namespace names.

<Note>Every index has at least one namespace called default namespace, whose name is the empty string `""`.</Note>
</ResponseField>

```sh curl
curl $UPSTASH_VECTOR_REST_URL/list-namespaces \
  -H "Authorization: Bearer $UPSTASH_VECTOR_REST_TOKEN"
```

</RequestExample>

```json 200 OK
{
    "result": ["", "ns0", "ns1"]
}
```

</ResponseExample>

# Query Vectors
Source: https://upstash.com/docs/vector/api/endpoints/query

<Tip>
  Query will run against the default namespace by default.
  You can use a different namespace by specifying it in the request path.
</Tip>

## Request

It is also possible to send a batch query request by providing an array
of fields below.

<ParamField body="vector" name="vector" type="number[]" required>
  The query vector
  <Note>The query vector should have the same dimensions as your index.</Note>
</ParamField>

<ParamField body="topK" type="number" default="10">
  The total number of the vectors that you want to receive as a query
  result. The response will be sorted based on the distance metric score,
  and at most `topK` many vectors will be returned.
</ParamField>
<ParamField body="includeMetadata" type="boolean" default="false">
  Whether to include the metadata of the vectors in the response, if any.
  It is recommended to set this to `true` to easily identify vectors.
</ParamField>
<ParamField body="includeVectors" type="boolean" default="false">
  Whether to include the vector values in the response.
  It is recommended to set this to `false` as the vector values can be
  quite big, and not needed most of the time.
</ParamField>
<ParamField body="includeData" type="boolean" default="false">
  Whether to include the data of the vectors in the response, if any.
</ParamField>
<ParamField body="filter" type="string" default="">
  [Metadata filter](/docs/vector/features/filtering) to apply.
</ParamField>
<ParamField body="weightingStrategy" type="string">
  For sparse vectors of sparse and hybrid indexes, specifies what kind of
  weighting strategy should be used while querying the matching non-zero
  dimension values of the query vector with the documents.

If not provided, no weighting will be used.

Only possible value is `IDF` (inverse document frequency).
</ParamField>
<ParamField body="fusionAlgorithm" type="string">
  Fusion algorithm to use while fusing scores
  from dense and sparse components of a hybrid index.

If not provided, defaults to `RRF` (Reciprocal Rank Fusion).

Other possible value is `DBSF` (Distribution-Based Score Fusion).
</ParamField>

## Path

<ParamField path="namespace" type="string" default="">
  The namespace to use.
  When no namespace is specified, the default namespace will be used.
</ParamField>

## Response

If the request was an array of a single element, or a JSON object,
an object with the following fields is returned.

If the request was an array of more than one items, an array of
objects below is returned, one for each query item.

<Note>
  For dense indexes, the score is normalized to always be between 0 and 1.
  The closer the score is to 1, the more similar the vector is to the query vector.
  This does not depend on the distance metric you use.

For sparse and hybrid indexes, scores can be arbitrary values, but the score
  will be higher for more similar vectors.
</Note>

<ResponseField name="Scores" type="Object[]">
  <Expandable defaultOpen="true">
    <ResponseField name="id" type="string" required>
      The id of the vector.
    </ResponseField>
    <ResponseField name="score" type="number" required>
      The similarity score of the vector, calculated based on the distance metric of your index.
    </ResponseField>
    <ResponseField name="vector" type="number[]">
      The dense vector value for dense and hybrid indexes.
    </ResponseField>
    <ResponseField name="sparseVector" type="Object[]">
      The sparse vector value for sparse and hybrid indexes.
      <Expandable defaultOpen="true">
        <ResponseField name="indices" type="number[]">
          Indices of the non-zero valued dimensions.
        </ResponseField>
        <ResponseField name="values" type="number[]">
          Values of the non-zero valued dimensions.
        </ResponseField>
      </Expandable>
    </ResponseField>
    <ResponseField name="metadata" type="Object">
      The metadata of the vector, if any.
    </ResponseField>
    <ResponseField name="data" type="string">
      The unstructured data of the vector, if any.
    </ResponseField>
  </Expandable>
</ResponseField>

```sh curl
curl $UPSTASH_VECTOR_REST_URL/query \
  -X POST \
  -H "Authorization: Bearer $UPSTASH_VECTOR_REST_TOKEN" \
  -d '{ "vector": [0.1, 0.2], "topK": 2, "includeMetadata": true }'
```

```sh curl (Namespace)
curl $UPSTASH_VECTOR_REST_URL/query/ns \
  -X POST \
  -H "Authorization: Bearer $UPSTASH_VECTOR_REST_TOKEN" \
  -d '{ "vector": [0.1, 0.2], "topK": 2, "includeMetadata": true }'
```

```sh curl (Batch Query)
curl "$UPSTASH_VECTOR_REST_URL/query" \
  -X POST \
  -H "Authorization: Bearer $UPSTASH_VECTOR_REST_TOKEN" \
  -d '[
        {
          "vector": [0.1, 0.2],
          "topK": 2,
          "includeMetadata": true
        },
        {
          "vector": [0.2, 0.3],
          "topK": 3
        }
      ]'
```

</RequestExample>

```json 200 OK
{
    "result": [
        {
            "id": "id-0",
            "score": 1.0,
            "metadata": {
                "link": "upstash.com"
            }
        },
        {
            "id": "id-1",
            "score": 0.99996454
        }
    ]
}
```
</ResponseExample>

# Query Data
Source: https://upstash.com/docs/vector/api/endpoints/query-data

<Warning>
  To use this endpoint, the index must be created with an [embedding model](/docs/vector/features/embeddingmodels).
</Warning>

<Tip>
  Query will run against the default namespace by default.
  You can use a different namespace by specifying it in the request path.
</Tip>

## Request

It is also possible to send a batch query request by providing an array
of fields below.

<ParamField body="data" name="data" type="string" required>
  The raw text data to embed and query.
</ParamField>
<ParamField body="topK" type="number" required default="10">
  The total number of the vectors that you want to receive as a query
  result. The response will be sorted based on the distance metric score,
  and at most `topK` many vectors will be returned.
</ParamField>
<ParamField body="includeMetadata" type="boolean" default="false">
  Whether to include the metadata of the vectors in the response, if any.
  It is recommended to set this to `true` to easily identify vectors.
</ParamField>
<ParamField body="includeVectors" type="boolean" default="false">
  Whether to include the vector values in the response.
  It is recommended to set this to `false` as the vector values can be
  quite big, and not needed most of the time.
</ParamField>
<ParamField body="includeData" type="boolean" default="false">
  Whether to include the data of the vectors in the response.
  When set to true, data will contain the raw text data used
  while upserting.
</ParamField>
<ParamField body="filter" type="string" default="">
  [Metadata filter](/docs/vector/features/filtering) to apply.
</ParamField>
<ParamField body="weightingStrategy" type="string">
  For sparse vectors of sparse and hybrid indexes, specifies what kind of
  weighting strategy should be used while querying the matching non-zero
  dimension values of the query vector with the documents.

If not provided, no weighting will be used.

If not provided, defaults to `RRF` (Reciprocal Rank Fusion).

Other possible value is `DBSF` (Distribution-Based Score Fusion).
</ParamField>
<ParamField body="queryMode" type="string">
    Query mode for hybrid indexes with Upstash-hosted
    embedding models.

Specifies whether to run the query in only the
    dense index, only the sparse index, or in both.

If not provided, defaults to `HYBRID`.

Possible values are `HYBRID`, `DENSE`, and `SPARSE`.
</ParamField>

## Path

<ParamField path="namespace" type="string" default="">
  The namespace to use.
  When no namespace is specified, the default namespace will be used.
</ParamField>

## Response

If the request was an array of a single element, or a JSON object,
an object with the following fields is returned.

If the request was an array of more than one items, an array of
objects below is returned, one for each query item.

For sparse and hybrid indexes, scores can be arbitrary values, but the score
  will be higher for more similar vectors.
</Note>

<ResponseField name="Scores" type="Object[]">
  <Expandable defaultOpen="true">
    <ResponseField name="id" type="string" required>
      The id of the vector.
    </ResponseField>
    <ResponseField name="score" type="number" required>
      The similarity score of the vector, calculated based on the distance metric of your index.
    </ResponseField>
    <ResponseField name="vector" type="number[]">
      The dense vector value for dense and hybrid indexes.
    </ResponseField>
    <ResponseField name="sparseVector" type="Object[]">
      The sparse vector value for sparse and hybrid indexes.
      <Expandable defaultOpen="true">
        <ResponseField name="indices" type="number[]">
          Indices of the non-zero valued dimensions.
        </ResponseField>
        <ResponseField name="values" type="number[]">
          Values of the non-zero valued dimensions.
        </ResponseField>
      </Expandable>
    </ResponseField>
    <ResponseField name="metadata" type="Object">
      The metadata of the vector, if any.
    </ResponseField>
    <ResponseField name="data" type="string">
      The textual data of the vector before embedding it.
    </ResponseField>
  </Expandable>
</ResponseField>

```sh curl
curl $UPSTASH_VECTOR_REST_URL/query-data \
  -X POST \
  -H "Authorization: Bearer $UPSTASH_VECTOR_REST_TOKEN" \
  -d '{ "data": "What is Upstash?", "topK": 2, "includeMetadata": true }'
```

```sh curl (Namespace)
curl $UPSTASH_VECTOR_REST_URL/query-data/ns \
  -X POST \
  -H "Authorization: Bearer $UPSTASH_VECTOR_REST_TOKEN" \
  -d '{ "data": "What is Upstash?", "topK": 2, "includeMetadata": true }'
```

```sh curl (Batch Query)
curl $UPSTASH_VECTOR_REST_URL/query-data \
  -X POST \
  -H "Authorization: Bearer $UPSTASH_VECTOR_REST_TOKEN" \
  -d '[
        {
          "data": "What is Upstash?",
          "topK": 2,
          "includeMetadata": true
        },
        {
          "data": "What is Upstash Vector?",
          "topK": 3
        }
      ]'
```

</RequestExample>

```json 200 OK
{
    "result": [
        {
            "id": "id-0",
            "score": 1.0,
            "metadata": {
                "link": "upstash.com"
            }
        },
        {
            "id": "id-1",
            "score": 0.99996454
        }
    ]
}
```

```json 422 Unprocessable Entity
{
    "error": "Embedding data for this index is not allowed. The index must be created with an embedding model to use it.",
    "status": 422
}
```

</ResponseExample>

# Range Vectors
Source: https://upstash.com/docs/vector/api/endpoints/range

<Tip>
  By default vectors from the default namespace will be iterated.
  You can use a different namespace by specifying it in the request path.
</Tip>

## Request

<ParamField body="cursor" type="string" required>
  The offset to the last retrieved vector. Should be set to `"0"` in the initial
  range.
</ParamField>
<ParamField body="prefix" type="string">
  Prefix of the vector ids to range over.
</ParamField>
<ParamField body="limit" type="number" required>
  The number of maximum vectors that you want in the response of range. (page
  size)
</ParamField>
<ParamField body="includeMetadata" type="boolean" default="false">
  Whether to include the metadata of the vectors in the response, if any.
  It is recommended to set this to `true` to easily identify vectors.
</ParamField>
<ParamField body="includeVectors" type="boolean" default="false">
  Whether to include the vector values in the response.
  It is recommended to set this to `false` as the vector values can be
  quite big, and not needed most of the time.
</ParamField>
<ParamField body="includeData" type="boolean" default="false">
  Whether to include the data of the vectors in the response, if any.
</ParamField>

## Path

<ParamField path="namespace" type="string" default="">
  The namespace to use.
  When no namespace is specified, the default namespace will be used.
</ParamField>

## Response

<ResponseField name="nextCursor" type="string" required>
  The offset for the next range. You should place this in the `cursor` field for
  the next range. It will be equal to empty string if there are no other vectors to range.
</ResponseField>

<ResponseField name="vectors" type="Object[]" required>
  <Expandable defaultOpen="true">
    <ResponseField name="id" type="string" required>
      The id of the vector.
    </ResponseField>
    <ResponseField name="vector" type="number[]">
      The dense vector value for dense and hybrid indexes.
    </ResponseField>
    <ResponseField name="sparseVector" type="Object[]">
      The sparse vector value for sparse and hybrid indexes.
      <Expandable defaultOpen="true">
        <ResponseField name="indices" type="number[]">
          Indices of the non-zero valued dimensions.
        </ResponseField>
        <ResponseField name="values" type="number[]">
          Values of the non-zero valued dimensions.
        </ResponseField>
      </Expandable>
    </ResponseField>
    <ResponseField name="metadata" type="Object">
      The metadata of the vector, if any.
    </ResponseField>
    <ResponseField name="data" type="string">
      The unstructured data of the vector, if any.
    </ResponseField>
  </Expandable>
</ResponseField>

```sh curl
curl $UPSTASH_VECTOR_REST_URL/range \
  -H "Authorization: Bearer $UPSTASH_VECTOR_REST_TOKEN" \
  -d '{ "cursor": "0", "limit": 2, "includeMetadata": true }'
```

```sh curl (Namespace)
curl $UPSTASH_VECTOR_REST_URL/range/ns \
  -H "Authorization: Bearer $UPSTASH_VECTOR_REST_TOKEN" \
  -d '{ "cursor": "0", "limit": 2, "includeMetadata": true }'
```

</RequestExample>

```json 200 OK
{
    "result": {
        "nextCursor": "2",
        "vectors": [
            {
                "id": "id-0",
                "metadata": {
                    "link": "upstash.com"
                }
            },
            {
                "id": "id-1"
            }
        ]
    }
}
```

</ResponseExample>

# Rename Namespace
Source: https://upstash.com/docs/vector/api/endpoints/rename-namespace

<Note>
  The default namespace, which is the empty string `""`, cannot be renamed.
</Note>

<Note>
  There should not be a namespace with the given new namespace name, unless the
  delete existing flag is passed.
</Note>

## Request

<ParamField body="namespace" type="string" required>
  The name of the namespace to rename.
</ParamField>

<ParamField body="newNamespace" type="string" required>
  The new name of the namespace.
</ParamField>

<ParamField body="deleteExisting" type="boolean" default="false">
  When the delete existing flag is passed, if there exists a namespace
  with the new namespace name, it is deleted before the rename operation.
</ParamField>

## Response

<ResponseField name="renamed" type="boolean">
  Whether the namespace is renamed or not.
</ResponseField>

```sh curl
curl $UPSTASH_VECTOR_REST_URL/rename-namespace \
  -X POST \
  -d '{ "namespace": "ns", "newNamespace": "newNs" }' \
  -H "Authorization: Bearer $UPSTASH_VECTOR_REST_TOKEN"
```

</RequestExample>

```json 200 OK
{
    "result": { "renamed": true }
}
```

</ResponseExample>

# Reset Namespace(s)
Source: https://upstash.com/docs/vector/api/endpoints/reset

The namespace will be completely empty after `/reset` is called, but will not be deleted.

<Tip>
  Reset operation will be performed against the default namespace by default.
  You can use a different namespace by specifying it in the request path.
</Tip>

## Request

This request doesn't require any additional data.

## Query

<ParamField query="all" type="string">
  When given, resets all namespaces of an index.
</ParamField>

## Path

<ParamField path="namespace" type="string" default="">
  The namespace to use.
  When no namespace is specified, the default namespace will be used.
</ParamField>

## Response

<ResponseField name="result" type="string">
  `"Success"` string.
</ResponseField>

```sh curl
curl $UPSTASH_VECTOR_REST_URL/reset \
  -X DELETE \
  -H "Authorization: Bearer $UPSTASH_VECTOR_REST_TOKEN"
```

```sh curl (Namespace)
curl $UPSTASH_VECTOR_REST_URL/reset/ns \
  -X DELETE \
  -H "Authorization: Bearer $UPSTASH_VECTOR_REST_TOKEN"
```

```sh curl (All Namespaces)
curl $UPSTASH_VECTOR_REST_URL/reset?all \
  -X DELETE \
  -H "Authorization: Bearer $UPSTASH_VECTOR_REST_TOKEN"
```

</RequestExample>

```json 200 OK
{
    "result": "Success"
}
```

</ResponseExample>

# Resume
Source: https://upstash.com/docs/vector/api/endpoints/resumable-query/resume

## Request

<ParamField body="uuid" type="string" required>
  The unique identifier returned from the start resumable query request.
</ParamField>

<ParamField body="additionalK" type="number" required>
  The number of additional results to fetch.
</ParamField>

## Response

<ResponseField name="Scores" type="Object[]">
  <Expandable defaultOpen="true">
    <ResponseField name="id" type="string" required>
      The id of the vector.
    </ResponseField>
    <ResponseField name="score" type="number" required>
      The similarity score of the vector, calculated based on the distance
      metric of your index.
    </ResponseField>
    <ResponseField name="vector" type="number[]">
      The dense vector value for dense and hybrid indexes.
    </ResponseField>
    <ResponseField name="sparseVector" type="Object[]">
      The sparse vector value for sparse and hybrid indexes.
      <Expandable defaultOpen="true">
        <ResponseField name="indices" type="number[]">
          Indices of the non-zero valued dimensions.
        </ResponseField>
        <ResponseField name="values" type="number[]">
          Values of the non-zero valued dimensions.
        </ResponseField>
      </Expandable>
    </ResponseField>
    <ResponseField name="metadata" type="Object">
      The metadata of the vector, if any.
    </ResponseField>
    <ResponseField name="data" type="string">
      The unstructured data of the vector, if any.
    </ResponseField>
  </Expandable>
</ResponseField>

```sh curl
curl $UPSTASH_VECTOR_REST_URL/resumable-query-next \
  -X POST \
  -H "Authorization: Bearer $UPSTASH_VECTOR_REST_TOKEN" \
  -d '{
    "uuid": "550e8400-e29b-41d4-a716-446655440000",
    "additionalK": 2
  }'
```

</RequestExample>

# Start with Data
Source: https://upstash.com/docs/vector/api/endpoints/resumable-query/start-with-data

## Request

<ParamField body="data" type="string" required>
  The text data to be embedded and used for querying.
</ParamField>

<ParamField body="includeVectors" type="boolean" default="false">
  Whether to include the vector values in the response. It is recommended to set
  this to `false` as the vector values can be quite big, and not needed most of
  the time.
</ParamField>

<ParamField body="includeData" type="boolean" default="false">
  Whether to include the data of the vectors in the response, if any.
</ParamField>

<ParamField body="filter" type="string" default="">
  [Metadata filter](/docs/vector/features/filtering) to apply.
</ParamField>

<ParamField body="maxIdle" type="number">
  Maximum idle time for the resumable query in seconds.
</ParamField>

<ParamField body="weightingStrategy" type="string">
  For sparse vectors of sparse and hybrid indexes, specifies what kind of
  weighting strategy should be used while querying the matching non-zero
  dimension values of the query vector with the documents.

If not provided, no weighting will be used.

Only possible value is `IDF` (inverse document frequency).
</ParamField>

<ParamField body="fusionAlgorithm" type="string">
  Fusion algorithm to use while fusing scores
  from dense and sparse components of a hybrid index.

If not provided, defaults to `RRF` (Reciprocal Rank Fusion).

Other possible value is `DBSF` (Distribution-Based Score Fusion).
</ParamField>

<ParamField body="queryMode" type="string">
    Query mode for hybrid indexes with Upstash-hosted
    embedding models.

Specifies whether to run the query in only the
    dense index, only the sparse index, or in both.

If not provided, defaults to `HYBRID`.

Possible values are `HYBRID`, `DENSE`, and `SPARSE`.
</ParamField>

## Path

<ParamField path="namespace" type="string" default="">
  The namespace to use. When no namespace is specified, the default namespace
  will be used.
</ParamField>

## Response

Same as Resumable Query.

```sh curl
curl $UPSTASH_VECTOR_REST_URL/resumable-query-data \
  -X POST \
  -H "Authorization: Bearer $UPSTASH_VECTOR_REST_TOKEN" \
  -d '{
    "data": "Hello world",
    "topK": 2,
    "includeMetadata": true,
    "maxIdle": 3600
  }'
```

</RequestExample>

# Start with Vector
Source: https://upstash.com/docs/vector/api/endpoints/resumable-query/start-with-vector

<Tip>
  Resumable queries allow you to fetch results in batches, which is useful for
  large result sets or when you want to implement pagination.
</Tip>

## Request

<ParamField body="vector" type="number[]" required>
  The query vector
  <Note>The query vector should have the same dimensions as your index.</Note>
</ParamField>

<ParamField body="includeData" type="boolean" default="false">
  Whether to include the data of the vectors in the response, if any.
</ParamField>

<ParamField body="filter" type="string" default="">
  [Metadata filter](/docs/vector/features/filtering) to apply.
</ParamField>

<ParamField body="maxIdle" type="number">
  Maximum idle time for the resumable query in seconds.
</ParamField>

If not provided, no weighting will be used.

Only possible value is `IDF` (inverse document frequency).
</ParamField>

<ParamField body="fusionAlgorithm" type="string">
  Fusion algorithm to use while fusing scores
  from dense and sparse components of a hybrid index.

If not provided, defaults to `RRF` (Reciprocal Rank Fusion).

Other possible value is `DBSF` (Distribution-Based Score Fusion).
</ParamField>

## Path

<ParamField path="namespace" type="string" default="">
  The namespace to use. When no namespace is specified, the default namespace
  will be used.
</ParamField>

## Response

<ResponseField name="uuid" type="string" required>
  A unique identifier for the resumable query.
</ResponseField>

<ResponseField name="scores" type="Object[]">
  <Expandable defaultOpen="true">
    <ResponseField name="id" type="string" required>
      The id of the vector.
    </ResponseField>
    <ResponseField name="score" type="number" required>
      The similarity score of the vector, calculated based on the distance
      metric of your index.
    </ResponseField>
    <ResponseField name="vector" type="number[]">
      The dense vector value for dense and hybrid indexes.
    </ResponseField>
    <ResponseField name="sparseVector" type="Object[]">
      The sparse vector value for sparse and hybrid indexes.
      <Expandable defaultOpen="true">
        <ResponseField name="indices" type="number[]">
          Indices of the non-zero valued dimensions.
        </ResponseField>
        <ResponseField name="values" type="number[]">
          Values of the non-zero valued dimensions.
        </ResponseField>
      </Expandable>
    </ResponseField>
    <ResponseField name="metadata" type="Object">
      The metadata of the vector, if any.
    </ResponseField>
    <ResponseField name="data" type="string">
      The unstructured data of the vector, if any.
    </ResponseField>
  </Expandable>
</ResponseField>

```sh curl
curl $UPSTASH_VECTOR_REST_URL/resumable-query \
  -X POST \
  -H "Authorization: Bearer $UPSTASH_VECTOR_REST_TOKEN" \
  -d '{
    "vector": [0.1, 0.2],
    "topK": 2,
    "includeMetadata": true,
    "maxIdle": 3600
  }'
```

```sh curl (Namespace)
curl $UPSTASH_VECTOR_REST_URL/resumable-query/ns \
  -X POST \
  -H "Authorization: Bearer $UPSTASH_VECTOR_REST_TOKEN" \
  -d '{
    "vector": [0.1, 0.2],
    "topK": 2,
    "includeMetadata": true,
    "maxIdle": 3600
  }'
```

</RequestExample>

```json 200 OK
{
  "uuid": "550e8400-e29b-41d4-a716-446655440000",
  "scores": [
    {
      "id": "id-0",
      "score": 1.0,
      "metadata": {
        "link": "upstash.com"
      }
    },
    {
      "id": "id-1",
      "score": 0.99996454
    }
  ]
}
```

</ResponseExample>

# Stop Resumable Query
Source: https://upstash.com/docs/vector/api/endpoints/resumable-query/stop

## Request

<ParamField body="uuid" type="string" required>
  The unique identifier of the resumable query to end.
</ParamField>

## Response

<ResponseField name="result" type="string">
  A success message indicating the query was ended.
</ResponseField>

```sh curl
curl $UPSTASH_VECTOR_REST_URL/resumable-query-end \
  -X POST \
  -H "Authorization: Bearer $UPSTASH_VECTOR_REST_TOKEN" \
  -d '{
    "uuid": "550e8400-e29b-41d4-a716-446655440000"
  }'
```

</RequestExample>

```json 200 OK
{
  "result": "Success"
}
```

</ResponseExample>

# Update Vector
Source: https://upstash.com/docs/vector/api/endpoints/update

<Tip>
  The vector will be updated int the default namespace by default.
  You can use a different namespace by specifying it in the request path.
</Tip>

## Request

You can update a vector value, data, or metadata; or any combination
of those.

<ParamField body="id" type="string" required>
  The id of the vector.
</ParamField>
<ParamField body="vector" type="number[]">
  The dense vector value to update to for dense and hybrid indexes.
  <Note>The vector should have the same dimensions as your index.</Note>
</ParamField>
<ParamField body="sparseVector" type="Object[]">
  The sparse vector value to update to for sparse and hybrid indexes.
  <Expandable defaultOpen="true">
    <ResponseField name="indices" type="number[]">
      Indices of the non-zero valued dimensions.
    </ResponseField>
    <ResponseField name="values" type="number[]">
      Values of the non-zero valued dimensions.
    </ResponseField>
  </Expandable>
</ParamField>
<ParamField body="data" type="string">
  The raw text data to update to.
  <Note>If the index is created with an [embedding model](/docs/vector/features/embeddingmodels)
      this will embed the data into a vector and will also update the vector, along with data.</Note>
</ParamField>
<ParamField body="metadata" type="Object">
  The metadata to update to.
</ParamField>
<ParamField body="metadataUpdateMode" type="string">
  Whether to overwrite the whole metadata while updating
  it, or patch the metadata (insert new fields or update or delete existing fields)
  according to the `RFC 7396 JSON Merge Patch` algorithm.

`OVERWRITE` for overwrite, `PATCH` for patch.
</ParamField>

<Note>
For hybrid indexes either none or both of `vector` and `sparseVector` fields
must be present. It is not allowed to update only `vector` or `sparseVector`.
</Note>

## Path

<ParamField path="namespace" type="string" default="">
  The namespace to use.
  When no namespace is specified, the default namespace will be used.
</ParamField>

## Response

<ResponseField name="updated" type="number">
  `1` if any vector is updated, `0` otherwise.
</ResponseField>

```sh curl
curl $UPSTASH_VECTOR_REST_URL/update \
  -X POST \
  -H "Authorization: Bearer $UPSTASH_VECTOR_REST_TOKEN" \
  -d '{ "id": "id-1", "metadata": { "link": "upstash.com" } }'
```

```sh curl (Namespace)
curl $UPSTASH_VECTOR_REST_URL/update/ns \
  -X POST \
  -H "Authorization: Bearer $UPSTASH_VECTOR_REST_TOKEN" \
  -d '{ "id": "id-2", "vector": [0.1, 0.2] }'
```

</RequestExample>

```json 200 OK
{
    "result": {
        "updated": 1
    }
}
```

</ResponseExample>

# Upsert Vectors
Source: https://upstash.com/docs/vector/api/endpoints/upsert

<Tip>
  The vector will be upserted into the default namespace by default.
  You can use a different namespace by specifying it in the request path.
</Tip>

## Request

You can either upsert a single vector, or multiple vectors in an array.

<ParamField body="id" type="string" required>
  The id of the vector.
</ParamField>
<ParamField body="vector" type="number[]">
  The dense vector value for dense and hybrid indexes.
  <Note>The vector should have the same dimensions as your index.</Note>
</ParamField>
<ParamField body="sparseVector" type="Object[]">
  The sparse vector value for sparse and hybrid indexes.
  <Expandable defaultOpen="true">
    <ResponseField name="indices" type="number[]">
      Indices of the non-zero valued dimensions.
    </ResponseField>
    <ResponseField name="values" type="number[]">
      Values of the non-zero valued dimensions.
    </ResponseField>
  </Expandable>
</ParamField>
<ParamField body="metadata" type="Object">
  The metadata of the vector. This makes identifying vectors
  on retrieval easier and can be used to with filters on queries.
</ParamField>
<ParamField body="data" type="string">
  The data of the vector. This is an unstructured raw text
  data, which can be anything associated with this vector.
</ParamField>

<Note>
For dense indexes, only `vector` should be provided, and `sparseVector` should not be set.

For sparse indexes, only `sparseVector` should be provided, and `vector` should not be set.

For hybrid indexes both of `vector` and `sparseVector` must be present.
</Note>

## Path

<ParamField path="namespace" type="string" default="">
  The namespace to use.
  When no namespace is specified, the default namespace will be used.
</ParamField>

## Response

<ResponseField name="result" type="string">
  `"Success"` string.
</ResponseField>

```sh curl
curl $UPSTASH_VECTOR_REST_URL/upsert \
  -X POST \
  -H "Authorization: Bearer $UPSTASH_VECTOR_REST_TOKEN" \
  -d '[
    { "id": "id-0", "vector": [0.1, 0.2], "metadata": { "link": "upstash.com" } },
    { "id": "id-1", "vector": [0.2, 0.3] }
  ]'
```

```sh curl (Namespace)
curl $UPSTASH_VECTOR_REST_URL/upsert/ns \
  -X POST \
  -H "Authorization: Bearer $UPSTASH_VECTOR_REST_TOKEN" \
  -d '{ "id": "id-2", "vector": [0.1, 0.2], "metadata": { "link": "upstash.com" } }'
```

</RequestExample>

```json 200 OK
{
    "result": "Success"
}
```

```json 422 Unprocessable Entity
{
    "error": "Invalid vector dimension: 2, expected: 256",
    "status": 422
}
```

</ResponseExample>

# Upsert Data
Source: https://upstash.com/docs/vector/api/endpoints/upsert-data

<Warning>
  To use this endpoint, the index must be created with an [embedding model](/docs/vector/features/embeddingmodels).
</Warning>

<Tip>
  Vector embedding of the raw text data will be upserted into the
  default namespace by default.
  You can use a different namespace by specifying it in the request path.
</Tip>

## Request

You can either upsert a single data, or multiple data in an array.

<ParamField body="id" type="string" required>
  The id of the vector.
</ParamField>
<ParamField body="data" type="string" required>
  The raw text data to embed and upsert.
</ParamField>
<ParamField body="metadata" type="Object">
  The metadata of the vector. This makes identifying vectors
  on retrieval easier and can be used to with filters on queries.
</ParamField>

<Note>
  Data field of the vector will be automatically set to the
  raw text data, so that you can access it later, during
  queries.
</Note>

## Path

<ParamField path="namespace" type="string" default="">
  The namespace to use.
  When no namespace is specified, the default namespace will be used.
</ParamField>

## Response

<ResponseField name="result" type="string">
  `"Success"` string.
</ResponseField>

```sh curl
curl $UPSTASH_VECTOR_REST_URL/upsert-data \
  -X POST \
  -H "Authorization: Bearer $UPSTASH_VECTOR_REST_TOKEN" \
  -d '[
    { "id": "id-0", "data": "Upstash is a serverless data platform.", "metadata": { "link": "upstash.com" } },
    { "id": "id-1", "data": "Upstash Vector is a serverless vector database." }
  ]'
```

```sh curl (Namespace)
curl $UPSTASH_VECTOR_REST_URL/upsert-data/ns \
  -X POST \
  -H "Authorization: Bearer $UPSTASH_VECTOR_REST_TOKEN" \
  -d '{ "id": "id-2", "data": "Upstash is a serverless data platform.", "metadata": { "link": "upstash.com" } }'
```

</RequestExample>

```json 200 OK
{
    "result": "Success"
}
```

```json 422 Unprocessable Entity
{
    "error": "Embedding data for this index is not allowed. The index must be created with an embedding model to use it.",
    "status": 422
}
```

</ResponseExample>

# Getting Started
Source: https://upstash.com/docs/vector/api/get-started

If you do not have a vector database already, follow [these steps](/docs/vector/overall/getstarted) to create one.

In the database details section of the Upstash Console, scroll down to `Connect` section and select the `cURL` tab. You can simply copy the curl expression and run on your terminal.

```shell
curl $UPSTASH_VECTOR_REST_URL/upsert \
  -H "Authorization: Bearer $UPSTASH_VECTOR_REST_TOKEN" \
  -d '{"id": "id-0", "vector": [0.87, 0.99]}'
```

## Response

REST API returns a JSON response. When command execution is successful, response JSON will have a single result field and its value will contain the Redis response.

Example:

```json
{ "result": "Success" }
```

When command execution is not successful, response JSON will have a single error field and its value will contain the error message.

Example:

```json
{
  "error": "Unauthorized: Invalid auth token",
  "status": 401
}
```

#### HTTP Response Codes

| Status Code              | Description                                                                                         |
| ------------------------ | --------------------------------------------------------------------------------------------------- |
| `200 OK`                 | When request is accepted and successfully executed.                                                 |
| `400 Bad Request`        | When there's a syntax error, an invalid/unsupported command is sent or command execution fails.     |
| `401 Unauthorized`       | When authentication fails; auth token is missing or invalid.                                        |
| `405 Method Not Allowed` | When an unsupported HTTP method is used. Only `HEAD`, `GET`, `POST`, and `PUT` methods are allowed. |

***

# Examples
Source: https://upstash.com/docs/vector/examples

# Algorithm
Source: https://upstash.com/docs/vector/features/algorithm

## Approximate Nearest Neighbor Search

The primary functionality of the vector store is straightforward: identifying the most similar vectors to a given vector.
While the concept is simple, translating it into a practical product poses significant challenges.

A simple and basic approach to searching in a vector database is to perform an exhaustive search by comparing a query vector to every other vector stored in the database one by one. However, this consumes too many resources and results in very high latencies, making it not very practical. To address this problem, Approximate Nearest Neighbor (`ANN`) algorithms are used. `ANN` search approximates the true nearest neighbor, which means it might not find the absolute closest point, but it will find one that's close enough, with a **low-latency** and by consuming **fewer resources**.
In the literature, the comparison of the results of `ANNS` with exhaustive search is called the recall rate.
The higher the recall rate the better the results.

Several `ANNS` algorithms, such as `HNSW`[1], `NSG`[2], and `DiskANN`[3], are available for use,
each with its distinct characteristics. One of the difficult problems in ANN algorithms is that indexing and querying vectors may require storing the whole data in memory. When the dataset is huge, then memory requirements for indexing may exceed available memory. `DiskANN` algorithm tries to solve this problem by using disk as the main storage for indexes and for performing queries directly on disk.`DiskANN` paper acknowledges that, if you try to store your vectors
in disk and use `HNSW` or `NSG`, you may end up with again very high latencies. `DiskANN` is focused
on serving queries from disk with **low-latency** and **good recall rate**.
And this helps Upstash Vector to be **cost-effective**, therefore cheaper compared to alternatives.

Even though `DiskANN` has its advantages, it also requires more work to be practical.
Main problem is that, you can't insert/update existing index without reindexing all the vectors.
For this problem, there is another improved paper `FreshDiskANN`[4]. `FreshDiskANN` improves `DiskANN` via introducing
a temporary index for up-to-date data in memory. Queries are served from both the temporary (up-to-date) index
and also from the disk. And these temporary indexes are merged to the disk from time-to-time behind the scene.

Upstash Vector is based on `DiskANN` and `FreshDiskANN` with more improvements based on our
tests and observations.

### References

1. Malkov, Y. A., Yashunin, D. A. (2016). _Efficient and Robust Approximate Nearest Neighbor Search Using Hierarchical Navigable Small World Graphs_. CoRR, abs/1603.09320 (2016). [https://arxiv.org/abs/1603.09320]
2. Fu, C., Xiang, C., Wang, C., Cai, D. (2019). _Fast Approximate Nearest Neighbor Search with Navigating Spreading-Out Graphs_. Proceedings of the VLDB, 12(5), 461–474. doi: 10.14778/3303753.3303754. [https://www.vldb.org/pvldb/vol12/p461-fu.pdf]
3. Subramanya, S. J., Devvrit, Kadekodi, R., Krishaswamy, R., Simhadri, H. V. (2019). _DiskANN: Fast Accurate Billion-Point Nearest Neighbor Search on a Single Node_. In Proceedings of the 33rd International Conference on Neural Information Processing Systems (NeurIPS '19), Article No.: 1233, Pages 13766–13776. [https://dl.acm.org/doi/abs/10.5555/3454287.3455520]
4. Singh, A., Subramanya, S. J., Krishnaswamy, R., Simhadri, H. V. (2021). _FreshDiskANN: A Fast and Accurate Graph-Based ANN Index for Streaming Similarity Search_. CoRR abs/2105.09613 (2021). [https://arxiv.org/abs/2105.09613]

# Embedding Models
Source: https://upstash.com/docs/vector/features/embeddingmodels

To store text in a vector database, it must first be converted into a vector,
also known as an embedding. Typically, this vectorization is done by a third
party.

By selecting an embedding model when you create your Upstash Vector database,
you can now upsert and query raw string data when using your database instead of
converting your text to a vector first. The vectorization is done automatically
by your selected model.

## Upstash Embedding Models - Video Guide

Let's look at how Upstash embeddings work, how the models we offer compare, and
which model is best for your use case.

## Models

Upstash Vector comes with a variety of embedding models that score well in the
[MTEB](https://huggingface.co/spaces/mteb/leaderboard) leaderboard, a benchmark
for measuring the performance of embedding models. They support use cases such
as classification, clustering, or retrieval.

You can choose the following general purpose models for dense and hybrid indexes:

| Name                                                                                                    | Dimension | Sequence Length | MTEB  |
| ------------------------------------------------------------------------------------------------------- | --------- | --------------- | ----- |
| [BAAI/bge-large-en-v1.5](https://huggingface.co/BAAI/bge-large-en-v1.5)                                 | 1024      | 512             | 64.23 |
| [BAAI/bge-base-en-v1.5](https://huggingface.co/BAAI/bge-base-en-v1.5)                                   | 768       | 512             | 63.55 |
| [BAAI/bge-small-en-v1.5](https://huggingface.co/BAAI/bge-small-en-v1.5)                                 | 384       | 512             | 62.17 |
| [BAAI/bge-m3](https://huggingface.co/BAAI/bge-m3)                                                       | 1024      | 8192            | *     |

<Note>
  The sequence length is not a hard limit. Models truncate the input
  appropriately when given a raw text data that would result in more tokens than
  the given sequence length. However, we recommend using appropriate models and
  not exceeding their sequence length to have more accurate results.
</Note>

<Note>
  MTEB score for the `BAAI/bge-m3` is not fully measured.
</Note>

For sparse and hybrid indexes, on the following models can be selected:

| Name                                              |
| ------------------------------------------------- |
| [BAAI/bge-m3](https://huggingface.co/BAAI/bge-m3) |
| [BM25](https://en.wikipedia.org/wiki/Okapi_BM25)  |

See [Creating Sparse Vectors](/docs/vector/features/sparseindexes#creating-sparse-vectors) for the details of the above models.

## Using a Model

To start using embedding models, create the index with a model of your choice.

<img />

Then, you can start upserting and querying raw text data without any extra
setup.

<Tabs>

```python
from upstash_vector import Index

index = Index(
    url="UPSTASH_VECTOR_REST_URL",
    token="UPSTASH_VECTOR_REST_TOKEN",
)

index.upsert(
    [("id-0", "Upstash is a serverless data platform.", {"field": "value"})],
)
```

</Tab>

```js
import { Index } from "@upstash/vector"

const index = new Index({
  url: "UPSTASH_VECTOR_REST_URL",
  token: "UPSTASH_VECTOR_REST_TOKEN",
})

await index.upsert({
  id: "id-0",
  data: "Upstash is a serverless data platform.",
  metadata: {
    field: "value",
  },
})
```

</Tab>

```go
package main

import (
	"github.com/upstash/vector-go"
)

func main() {
	index := vector.NewIndex("UPSTASH_VECTOR_REST_URL", "UPSTASH_VECTOR_REST_TOKEN")

index.UpsertData(vector.UpsertData{
		Id:       "id-0",
		Data:     "Upstash is a serverless data platform.",
		Metadata: map[string]any{"field": "value"},
	})
}
```

</Tab>

```php
use Upstash\Vector\Index;
use Upstash\Vector\DataUpsert;

$index = new Index(
  url: 'UPSTASH_VECTOR_REST_URL',
  token: 'UPSTASH_VECTOR_REST_TOKEN',
);

$index->upsertData(new DataUpsert(
  id: 'id-0',
  data: 'Upstash is a serverless data platform.',
  metadata: [
    'field' => 'value',
  ],
));
```

</Tab>

```shell
curl $UPSTASH_VECTOR_REST_URL/upsert-data \
  -X POST \
  -H "Authorization: Bearer $UPSTASH_VECTOR_REST_TOKEN" \
  -d '{"id": "1", "data": "Upstash is a serverless data platform.", "metadata": {"field": "value"}}'
```

</Tab>

</Tabs>

<Tabs>

```python
from upstash_vector import Index

index = Index(
    url="UPSTASH_VECTOR_REST_URL",
    token="UPSTASH_VECTOR_REST_TOKEN",
)

index.query(
    data="What is Upstash?",
    top_k=1,
    include_metadata=True,
)
```

</Tab>

```js
import { Index } from "@upstash/vector"

const index = new Index({
  url: "UPSTASH_VECTOR_REST_URL",
  token: "UPSTASH_VECTOR_REST_TOKEN",
})

await index.query({
  data: "What is Upstash?",
  topK: 1,
  includeMetadata: true,
})
```

</Tab>

```go
package main

import (
	"github.com/upstash/vector-go"
)

func main() {
	index := vector.NewIndex("UPSTASH_VECTOR_REST_URL", "UPSTASH_VECTOR_REST_TOKEN")

index.QueryData(vector.QueryData{
		Data:            "What is Upstash?",
		TopK:            1,
		IncludeMetadata: true,
	})
}
```

</Tab>

```php
use Upstash\Vector\Index;
use Upstash\Vector\DataQuery;

$index = new Index(
  url: 'UPSTASH_VECTOR_REST_URL',
  token: 'UPSTASH_VECTOR_REST_TOKEN',
);

$index->queryData(new DataQuery(
  data: 'What is Upstash?',
  topK: 1,
  includeMetadata: true,
));
```

</Tab>

```shell
curl $UPSTASH_VECTOR_REST_URL/query-data \
  -H "Authorization: Bearer $UPSTASH_VECTOR_REST_TOKEN" \
  -d '{"data": "What is Upstash?", "topK": 1, "includeMetadata": "true"}'
```

</Tab>

</Tabs>

# Metadata Filtering
Source: https://upstash.com/docs/vector/features/filtering

You can further restrict the vector similarity search by providing a filter based on a specific metadata criteria.

Queries with metadata filters only return vectors which have metadata matching with the filter.

Upstash Vector allows you to filter 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 vectors 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` vectors may be returned.

## Filter Syntax

A filter has a syntax that resembles SQL, which consists of operators on object keys and boolean operators
to combine them.

Assuming you have a metadata like below:

```json
{
    "city": "Istanbul",
    "country": "Turkey",
    "is_capital": false,
    "population": 15460000,
    "geography": {
        "continent": "Asia",
        "coordinates": {
            "latitude": 41.0082,
            "longitude": 28.9784
        }
    },
    "economy": {
        "currency": "TRY",
        "major_industries": [
            "Tourism",
            "Textiles",
            "Finance"
        ]
    }
}
```

Then, you can query similar vectors with a filter like below:

<Tabs>

```python
from upstash_vector import Index

index = Index(
  url="UPSTASH_VECTOR_REST_URL",
  token="UPSTASH_VECTOR_REST_TOKEN",
)

index.query(
  vector=[0.9215, 0.3897],
  filter="population >= 1000000 AND geography.continent = 'Asia'",
  top_k=5,
  include_metadata=True
)
```

</Tab>

```js
import { Index } from "@upstash/vector"

const index = new Index({
  url: "UPSTASH_VECTOR_REST_URL",
  token: "UPSTASH_VECTOR_REST_TOKEN",
})

await index.query({
  vector: [0.9215, 0.3897],
  filter: "population >= 1000000 AND geography.continent = 'Asia'",
  topK: 5,
  includeMetadata: true,
});
```

</Tab>

```go
package main

import (
	"github.com/upstash/vector-go"
)

func main() {
	index := vector.NewIndex("UPSTASH_VECTOR_REST_URL", "UPSTASH_VECTOR_REST_TOKEN")

index.Query(vector.Query{
		Vector:          []float32{0.9215, 0.3897},
		Filter:          `population >= 1000000 AND geography.continent = 'Asia'`,
		TopK:            5,
		IncludeMetadata: true,
	})
}
```

</Tab>

```php
use Upstash\Vector\Index;
use Upstash\Vector\VectorQuery;

$index = new Index(
  url: 'UPSTASH_VECTOR_REST_URL',
  token: 'UPSTASH_VECTOR_REST_TOKEN',
);

$index->query(new VectorQuery(
  vector: [0.9215, 0.3897],
  topK: 5,
  includeMetadata: true,
  filter: "population >= 1000000 AND geography.continent = 'Asia'",
));
```

</Tab>

```shell
curl $UPSTASH_VECTOR_REST_URL/query \
  -H "Authorization: Bearer $UPSTASH_VECTOR_REST_TOKEN" \
  -d '{
   "vector":[0.9215,0.3897],
   "topK" : 5,
   "filter": "population >= 1000000 AND geography.continent = \"Asia\"",
   "includeMetadata": true
}'
```

</Tab>

</Tabs>

### Operators

#### Equals (=)

The `equals` operator filters keys whose values are equal to the given literal.

It is applicable to _string_, _number_, and _boolean_ values.

```SQL
country = 'Turkey' AND population = 15460000 AND is_capital = false
```

#### Not Equals (!=)

The `not equals` operator filters keys whose values are not equal to the given literal.

It is applicable to _string_, _number_, and _boolean_ values.

```SQL
country != 'Germany' AND population != 12500000 AND is_capital != true
```

#### Less Than (\<)

The `less than` operator filters keys whose values are less than the given literal.

It is applicable to _number_ values.

```SQL
population < 20000000 OR geography.coordinates.longitude < 30.0
```

#### Less Than or Equals (\<=)

The `less than or equals` operator filters keys whose values are less than or equal to the given literal.

It is applicable to _number_ values.

```SQL
population <= 20000000 OR geography.coordinates.longitude <= 30.0
```

#### Greater Than (>)

The `greater than` operator filters keys whose values are greater than the given literal.

It is applicable to _number_ values.

```SQL
population > 10000000 OR geography.coordinates.latitude > 39.5
```

#### Greater Than or Equals (>=)

The `greater than or equals` operator filters keys whose values are greater than or equal to the given literal.

It is applicable to _number_ values.

```SQL
population >= 10000000 OR geography.coordinates.latitude >= 39.5
```

#### Glob

The `glob` operator filters keys 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 city names whose second character is `s` or `z`,
and ends with anything other than `m` to `z`.

```SQL
city GLOB '?[sz]*[^m-z]'
```

#### Not Glob

The `not glob` operator filters keys 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 city names whose first character is anything other than `A`.

```SQL
city NOT GLOB 'A*'
```

#### In

The `in` operator filters keys 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 keys 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 keys 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 keys 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 keys which have the given JSON field.

```SQL
HAS FIELD geography.coordinates
```

#### Has Not Field

The `has not field` operator filters keys 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 keys by referencing them with the `.` accessor.

Nested objects 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.

# Hybrid Indexes
Source: https://upstash.com/docs/vector/features/hybridindexes

Dense indexes are useful to perform semantic searches over
a dataset to find the most similar items quickly. It relies on the
embedding models to generate dense vectors that are similar to each
other for similar concepts. And, they do it well for the
data or the domain of the data that the embedding model is trained on.
But they sometimes fail, especially in the case where the data
is out of the training domain of the model. For such cases, a more traditional
exact search with sparse vectors performs better.

Hybrid indexes allow you to combine the best of these two worlds so that
you can get semantically similar results, and enhance them with exact
token/word matching to make the query results more relevant.

Upstash supports hybrid indexes that manage a dense and a sparse index
component for you. When you perform a query, it queries both the dense
and the sparse index and fuses the results.

## Creating Dense And Sparse Vectors

Since a hybrid index is a combination of a dense and a sparse index,
you can use the same methods you have used for dense and sparse indexes,
and combine them.

Upstash allows you to upsert and query dense and sparse vectors to
give you full control over the models you would use.

Also, to make embedding easier for you, Upstash provides some hosted
models and allows you to upsert and query text data. Behind the scenes,
the text data is converted to dense and sparse vectors.

You can create your index with a dense and sparse embedding model
to use this feature.

## Using Hybrid Indexes

### Upserting Dense and Sparse Vectors

You can upsert dense and sparse vectors into Upstash Vector indexes in two different ways.

#### Upserting Dense and Sparse Vectors

You can upsert dense and sparse vectors into the index as follows:

<Tabs>

```python
from upstash_vector import Index, Vector
from upstash_vector.types import SparseVector

index = Index(
    url="UPSTASH_VECTOR_REST_URL",
    token="UPSTASH_VECTOR_REST_TOKEN",
)

index.upsert(
    vectors=[
        Vector(id="id-0", vector=[0.1, 0.5], sparse_vector=SparseVector([1, 2], [0.1, 0.2])),
        Vector(id="id-1", vector=[0.3, 0.7], sparse_vector=SparseVector([123, 44232], [0.5, 0.4])),
    ]
)
```

</Tab>

```js
import { Index } from "@upstash/vector"

const index = new Index({
  url: "UPSTASH_VECTOR_REST_URL",
  token: "UPSTASH_VECTOR_REST_TOKEN",
})

await index.upsert([{
  id: 'id-0',
  vector: [0.1, 0.5],
  sparseVector: {
    indices: [2, 3],
    values: [0.13, 0.87],
  },
}])
```

</Tab>

```go
package main

import (
	"github.com/upstash/vector-go"
)

func main() {
	index := vector.NewIndex(
		"UPSTASH_VECTOR_REST_URL",
		"UPSTASH_VECTOR_REST_TOKEN",
	)

err := index.UpsertMany([]vector.Upsert{
		{
			Id:     "id-0",
			Vector: []float32{0.1, 0.5},
			SparseVector: &vector.SparseVector{
				Indices: []int32{1, 2},
				Values:  []float32{0.1, 0.2},
			},
		},
		{
			Id:     "id-1",
			Vector: []float32{0.3, 0.7},
			SparseVector: &vector.SparseVector{
				Indices: []int32{123, 44232},
				Values:  []float32{0.5, 0.4},
			},
		},
	})
}
```

</Tab>

```php
use Upstash\Vector\Index;
use Upstash\Vector\VectorUpsert;
use Upstash\Vector\SparseVector;

use function Upstash\Vector\createRandomVector;

$index = new Index(
  url: 'UPSTASH_VECTOR_REST_URL',
  token: 'UPSTASH_VECTOR_REST_TOKEN',
);

$index->upsert(new VectorUpsert(
  id: 'id-0',
  vector: createRandomVector(384),
  sparseVector: new SparseVector(
    indices: [1, 2, 3],
    values: [5, 6, 7],
  ),
));
```

</Tab>

```shell
curl $UPSTASH_VECTOR_REST_URL/upsert \
  -H "Authorization: Bearer $UPSTASH_VECTOR_REST_TOKEN" \
  -d '[
    {"id": "id-0", "vector": [0.1, 0.5], "sparseVector": {"indices": [1, 2], "values": [0.1, 0.2]}},
    {"id": "id-1", "vector": [0.3, 0.7], "sparseVector": {"indices": [123, 44232], "values": [0.5, 0.4]}}
  ]'
```

</Tab>

</Tabs>

Note that, for hybrid indexes, you have to provide both dense and sparse
vectors. You can't omit one or both.

#### Upserting Text Data

If you created the hybrid index with Upstash-hosted dense and sparse embedding models,
you can upsert text data, and Upstash can embed it behind the scenes.

<Tabs>

```python
from upstash_vector import Index, Vector

index = Index(
    url="UPSTASH_VECTOR_REST_URL",
    token="UPSTASH_VECTOR_REST_TOKEN",
)

index.upsert(
    vectors=[
        Vector(id="id-0", data="Upstash Vector provides dense and sparse embedding models."),
        Vector(id="id-1", data="You can upsert text data with these embedding models."),
    ]
)
```

</Tab>

```js
import { Index } from "@upstash/vector"

const index = new Index({
  url: "UPSTASH_VECTOR_REST_URL",
  token: "UPSTASH_VECTOR_REST_TOKEN",
})

await index.upsert([
  {
    id: 'id-0',
    data: "Upstash Vector provides dense and sparse embedding models.",
  }
])
```

</Tab>

```go
package main

import (
	"github.com/upstash/vector-go"
)

func main() {
	index := vector.NewIndex(
		"UPSTASH_VECTOR_REST_URL",
		"UPSTASH_VECTOR_REST_TOKEN",
	)

err := index.UpsertData(vector.UpsertData{
		Id:   "id-0",
		Data: "Upstash Vector provides dense and sparse embedding models.",
	})
}
```

</Tab>

```php
use Upstash\Vector\Index;
use Upstash\Vector\DataUpsert;

$index = new Index(
  url: 'UPSTASH_VECTOR_REST_URL',
  token: 'UPSTASH_VECTOR_REST_TOKEN',
);

$index->upsertData(new DataUpsert(
  id: 'id-0',
  data: 'Upstash Vector provides dense and sparse embedding models.',
));
```

</Tab>

```shell
curl $UPSTASH_VECTOR_REST_URL/upsert-data \
  -H "Authorization: Bearer $UPSTASH_VECTOR_REST_TOKEN" \
  -d '[
    {"id": "id-0", "data": "Upstash Vector provides dense and sparse embedding models."},
    {"id": "id-1", "data": "You can upsert text data with these embedding models."}
  ]'
```

</Tab>

</Tabs>

### Querying Dense and Sparse Vectors

Similar to upserts, you can query dense and sparse vectors in two different ways.

#### Querying with Dense and Sparse Vectors

Hybrid indexes can be queried by providing dense and sparse vectors.

<Tabs>

```python
from upstash_vector import Index
from upstash_vector.types import SparseVector

index = Index(
    url="UPSTASH_VECTOR_REST_URL",
    token="UPSTASH_VECTOR_REST_TOKEN",
)

index.query(
    vector=[0.5, 0.4],
    sparse_vector=SparseVector([3, 5], [0.3, 0.5]),
    top_k=5,
    include_metadata=True,
)
```

</Tab>

```js
import { Index } from "@upstash/vector"

const index = new Index({
  url: "UPSTASH_VECTOR_REST_URL",
  token: "UPSTASH_VECTOR_REST_TOKEN",
})

await index.query({
  vector: [0.5, 0.4],
  sparseVector: {
    indices: [2, 3],
    values: [0.13, 0.87],
  },
  includeData: true,
  topK: 3,
})
```

</Tab>

```go
package main

import (
	"github.com/upstash/vector-go"
)

func main() {
	index := vector.NewIndex(
		"UPSTASH_VECTOR_REST_URL",
		"UPSTASH_VECTOR_REST_TOKEN",
	)

scores, err := index.Query(vector.Query{
		Vector: []float32{0.5, 0.4},
		SparseVector: &vector.SparseVector{
			Indices: []int32{3, 5},
			Values:  []float32{0.3, 05},
		},
		TopK:            5,
		IncludeMetadata: true,
	})
}
```

</Tab>

```php
use Upstash\Vector\Index;
use Upstash\Vector\VectorQuery;
use Upstash\Vector\SparseVector;

$index = new Index(
  url: 'UPSTASH_VECTOR_REST_URL',
  token: 'UPSTASH_VECTOR_REST_TOKEN',
);

$index->query(new VectorQuery(
  vector: [0.5, 0.4],
  sparseVector: new SparseVector(
    indices: [3, 5],
    values: [0.3, 0.5],
  ),
  topK: 5,
  includeMetadata: true,
));
```

</Tab>

```shell
curl $UPSTASH_VECTOR_REST_URL/query \
  -H "Authorization: Bearer $UPSTASH_VECTOR_REST_TOKEN" \
  -d '{"vector": [0.5, 0.4], "sparseVector": {"indices": [3, 5], "values": [0.3, 0.5]}, "topK": 5, "includeMetadata": true}'
```

</Tab>

</Tabs>

The query results will be fused scores from the dense and sparse indexes.

#### Querying with Text Data

If you created the hybrid index with Upstash-hosted dense and sparse embedding models,
you can query with text data, and Upstash can embed it behind the scenes
before performing the actual query.

<Tabs>

```python
from upstash_vector import Index

index = Index(
    url="UPSTASH_VECTOR_REST_URL",
    token="UPSTASH_VECTOR_REST_TOKEN",
)

index.query(
    data="Upstash Vector",
    top_k=5,
)
```

</Tab>

```js
import { Index } from "@upstash/vector"

const index = new Index({
  url: "UPSTASH_VECTOR_REST_URL",
  token: "UPSTASH_VECTOR_REST_TOKEN",
})

await index.query(
  {
    data: "Upstash Vector",
    topK: 1,
  },
)
```

</Tab>

```go
package main

import (
	"github.com/upstash/vector-go"
)

func main() {
	index := vector.NewIndex(
		"UPSTASH_VECTOR_REST_URL",
		"UPSTASH_VECTOR_REST_TOKEN",
	)

scores, err := index.QueryData(vector.QueryData{
		Data: "Upstash Vector",
		TopK: 5,
	})
}
```

</Tab>

```php
use Upstash\Vector\Index;
use Upstash\Vector\DataQuery;

$index = new Index(
  url: 'UPSTASH_VECTOR_REST_URL',
  token: 'UPSTASH_VECTOR_REST_TOKEN',
);

$index->queryData(new DataQuery(
  data: 'Upstash Vector',
  topK: 5,
  includeMetadata: true,
));
```

</Tab>

```shell
curl $UPSTASH_VECTOR_REST_URL/query-data \
  -H "Authorization: Bearer $UPSTASH_VECTOR_REST_TOKEN" \
  -d '{"data": "Upstash Vector", "topK": 5}'
```

</Tab>

</Tabs>

### Fusing Dense And Sparse Query Scores

One of the most crucial parts of the hybrid search pipeline is the step
where we fuse or rerank dense and sparse search results.

By default, Upstash returns the hybrid query results by fusing/reranking
the dense and the sparse search results. It provides two fusing algorithms
to choose from to do so.

#### Reciprocal Rank Fusion

RRF is a method for combining results from dense and sparse indexes.
It focuses on the order of results, not their scores. Each result's score
is mapped using the formula:

```
Mapped Score = 1 / (rank + K)
```

Here, rank is the position of the result in the dense or sparse scores, and `K`
is a constant set to `60`.

If a result appears in both the dense and sparse indexes, its mapped scores are
added together. If it appears in only one of the indexes, its score remains unchanged.
After all scores are processed, the results are sorted by their combined scores,
and the top-K results are returned.

RRF effectively combines rankings from different sources, making use of their strengths,
while keeping the process simple and focusing on the order of results.

By default, hybrid indexes use RRF to fuse dense and sparse scores. It can be explicitly
set for queries as follows:

<Tabs>

```python
from upstash_vector import Index
from upstash_vector.types import FusionAlgorithm, SparseVector

index = Index(
    url="UPSTASH_VECTOR_REST_URL",
    token="UPSTASH_VECTOR_REST_TOKEN",
)

index.query(
    vector=[0.5, 0.4],
    sparse_vector=SparseVector([3, 5], [0.3, 0.5]),
    fusion_algorithm=FusionAlgorithm.RRF,
)
```

</Tab>

```js
import { FusionAlgorithm, Index } from "@upstash/vector";

const index = new Index({
  url: "UPSTASH_VECTOR_REST_URL",
  token: "UPSTASH_VECTOR_REST_TOKEN",
});

await index.query({
  vector: [0.5, 0.4],
  sparseVector: {
    indices: [2, 3],
    values: [0.13, 0.87],
  },
  fusionAlgorithm: FusionAlgorithm.RRF,
  topK: 3,
});
```

</Tab>

```go
package main

import (
	"github.com/upstash/vector-go"
)

func main() {
	index := vector.NewIndex(
		"UPSTASH_VECTOR_REST_URL",
		"UPSTASH_VECTOR_REST_TOKEN",
	)

scores, err := index.Query(vector.Query{
		Vector: []float32{0.5, 0.4},
		SparseVector: &vector.SparseVector{
			Indices: []int32{3, 5},
			Values:  []float32{0.3, 05},
		},
		FusionAlgorithm: vector.FusionAlgorithmRRF,
	})
}
```

</Tab>

```php
use Upstash\Vector\Index;
use Upstash\Vector\VectorQuery;
use Upstash\Vector\SparseVector;
use Upstash\Vector\Enums\FusionAlgorithm;

$index = new Index(
  url: 'UPSTASH_VECTOR_REST_URL',
  token: 'UPSTASH_VECTOR_REST_TOKEN',
);

$index->query(new VectorQuery(
  vector: [0.5, 0.4],
  sparseVector: new SparseVector(
    indices: [3, 5],
    values: [0.3, 0.5],
  ),
  topK: 5,
  includeMetadata: true,
  fusionAlgorithm: FusionAlgorithm::RECIPROCAL_RANK_FUSION,
));
```

</Tab>

</Tab>

</Tabs>

#### Distribution-Based Score Fusion

DBSF is a method for combining results from dense and sparse indexes by considering
the distribution of scores. Each score is normalized using the formula:

```
                        s − (μ − 3 * σ)
Normalized Score = -------------------------
                   (μ + 3 * σ) − (μ − 3 * σ)
```

Where:

* `s` is the score.
* `μ` is the mean of the scores.
* `σ` is the standard deviation.
* `(μ − 3 * σ)` represents the minimum value (lower tail of the distribution).
* `(μ + 3 * σ)` represents the maximum value (upper tail of the distribution).

This formula scales each score to fit between 0 and 1 based on the range defined by
the distribution's tails.

If a result appears in both the dense and sparse indexes, the normalized scores
are added together. For results that appear in only one index, the individual
normalized score is used. After all scores are processed, the results are
sorted by their combined scores, and the top-K results are returned.

Unlike RRF, this approach takes the distribution of scores into account,
making it more sensitive to variations in score ranges from the dense and sparse indexes.

It can be used in hybrid index queries as follows:

<Tabs>

```python
from upstash_vector import Index
from upstash_vector.types import FusionAlgorithm, SparseVector

index = Index(
    url="UPSTASH_VECTOR_REST_URL",
    token="UPSTASH_VECTOR_REST_TOKEN",
)

index.query(
    vector=[0.5, 0.4],
    sparse_vector=SparseVector([3, 5], [0.3, 0.5]),
    fusion_algorithm=FusionAlgorithm.DBSF,
)
```

</Tab>

```js
import { FusionAlgorithm, Index } from "@upstash/vector";

const index = new Index({
  url: "UPSTASH_VECTOR_REST_URL",
  token: "UPSTASH_VECTOR_REST_TOKEN",
});

await index.query({
  vector: [0.5, 0.4],
  sparseVector: {
    indices: [2, 3],
    values: [0.13, 0.87],
  },
  fusionAlgorithm: FusionAlgorithm.DBSF,
  topK: 3,
});
```

</Tab>

```go
package main

import (
	"github.com/upstash/vector-go"
)

func main() {
	index := vector.NewIndex(
		"UPSTASH_VECTOR_REST_URL",
		"UPSTASH_VECTOR_REST_TOKEN",
	)

</Tab>

```php
use Upstash\Vector\Index;
use Upstash\Vector\VectorQuery;
use Upstash\Vector\SparseVector;
use Upstash\Vector\Enums\FusionAlgorithm;

$index = new Index(
  url: 'UPSTASH_VECTOR_REST_URL',
  token: 'UPSTASH_VECTOR_REST_TOKEN',
);

</Tab>

</Tab>

</Tabs>

#### Using a Custom Reranker

For some use cases, you might need something other than RRF or DBSF.
Maybe you want to use the [bge-reranker-v2-m3](https://huggingface.co/BAAI/bge-reranker-v2-m3),
or any reranker model or algorithm of your choice on the dense and sparse
components of the hybrid index.

For such scenarios, hybrid indexes allow you to perform queries over
only dense and only sparse components. This way, the hybrid index
would return semantically similar vectors from the dense index, and
exact query matches from the sparse index. Then, you can rerank them
as you like.

<Tabs>

```python
from upstash_vector import Index
from upstash_vector.types import SparseVector

index = Index(
    url="UPSTASH_VECTOR_REST_URL",
    token="UPSTASH_VECTOR_REST_TOKEN",
)

dense_results = index.query(
    vector=[0.5, 0.4],
)

sparse_results = index.query(
    sparse_vector=SparseVector([3, 5], [0.3, 0.5]),
)

# Rerank dense and sparse results as you like here
```

</Tab>

```js
import { Index } from "@upstash/vector"

const index = new Index({
  url: "UPSTASH_VECTOR_REST_URL",
  token: "UPSTASH_VECTOR_REST_TOKEN",
})

const denseResults = await index.query(
  {
    vector: [0.5, 0.4],
    topK: 3,
  },
)

const sparseResults = await index.query(
  {
    sparseVector: {
      indices: [2, 3],
      values: [0.13, 0.87],
    },
    topK: 3,
  },
)

// Rerank dense and sparse results as you like here
```

</Tab>

```go
package main

import (
	"github.com/upstash/vector-go"
)

func main() {
	index := vector.NewIndex(
		"UPSTASH_VECTOR_REST_URL",
		"UPSTASH_VECTOR_REST_TOKEN",
	)

denseScores, err := index.Query(vector.Query{
		Vector: []float32{0.5, 0.4},
	})

sparseScores, err := index.Query(vector.Query{
		SparseVector: &vector.SparseVector{
			Indices: []int32{3, 5},
			Values:  []float32{0.3, 05},
		},
	})

// Rerank dense and sparse results as you like here
}
```

</Tab>

```php
use Upstash\Vector\Index;
use Upstash\Vector\VectorQuery;
use Upstash\Vector\SparseVector;

$index = new Index(
  url: 'UPSTASH_VECTOR_REST_URL',
  token: 'UPSTASH_VECTOR_REST_TOKEN',
);

$denseResults = $index->query(new VectorQuery(
  vector: [0.5, 0.4],
  topK: 3,
));

$sparseResults = $index->query(new VectorQuery(
  sparseVector: new SparseVector(
    indices: [3, 5],
    values: [0.3, 0.5],
  ),
  topK: 3,
));

// Rerank dense and sparse results as you like here
```

</Tab>

```shell
curl $UPSTASH_VECTOR_REST_URL/query \
  -H "Authorization: Bearer $UPSTASH_VECTOR_REST_TOKEN" \
  -d '{"vector": [0.5, 0.4]}'

curl $UPSTASH_VECTOR_REST_URL/query \
  -H "Authorization: Bearer $UPSTASH_VECTOR_REST_TOKEN" \
  -d '{"sparseVector": {"indices": [3, 5], "values": [0.3, 0.5]}}'
```

</Tab>

</Tabs>

#### Using a Custom Reranker with Text Data

Similar the section above, you might want to use a custom reranker
for the hybrid indexes created with Upstash-hosted embedding models.

For such scenarios, hybrid indexes with Upstash-hosted embedding models
allow you to perform queries over only dense and only sparse components.
This way, the hybrid index would return semantically similar vectors
from the dense index by embedding the text data into a dense vector,
and exact query matches from the sparse index by embedding the text data
into a sparse vector. Then, you can rerank them as you like.

<Tabs>

```python
from upstash_vector import Index
from upstash_vector.types import SparseVector, QueryMode

index = Index(
    url="UPSTASH_VECTOR_REST_URL",
    token="UPSTASH_VECTOR_REST_TOKEN",
)

dense_results = index.query(
    data="Upstash Vector",
    query_mode=QueryMode.DENSE,
)

sparse_results = index.query(
    data="Upstash Vector",
    query_mode=QueryMode.SPARSE,
)

# Rerank dense and sparse results as you like here
```

</Tab>

```js
import { Index, QueryMode } from "@upstash/vector"

const index = new Index({
  url: "UPSTASH_VECTOR_REST_URL",
  token: "UPSTASH_VECTOR_REST_TOKEN",
})

const denseResults = await index.query({
  data: "Upstash Vector",
  queryMode: QueryMode.DENSE,
})

const sparseResults = await index.query({
  data: "Upstash Vector",
  queryMode: QueryMode.SPARSE,
})

// Rerank dense and sparse results as you like here
```

</Tab>

```go
package main

import (
	"github.com/upstash/vector-go"
)

func main() {
	index := vector.NewIndex(
		"UPSTASH_VECTOR_REST_URL",
		"UPSTASH_VECTOR_REST_TOKEN",
	)

denseScores, err := index.QueryData(vector.QueryData{
		Data:      "Upstash Vector",
		QueryMode: vector.QueryModeDense,
	})

sparseScores, err := index.QueryData(vector.QueryData{
		Data:      "Upstash Vector",
		QueryMode: vector.QueryModeSparse,
	})

// Rerank dense and sparse results as you like here
}
```

</Tab>

```php
use Upstash\Vector\Index;
use Upstash\Vector\DataQuery;
use Upstash\Vector\Enums\QueryMode;

$index = new Index(
  url: 'UPSTASH_VECTOR_REST_URL',
  token: 'UPSTASH_VECTOR_REST_TOKEN',
);

$denseResults = $index->queryData(new DataQuery(
  data: 'Upstash Vector',
  topK: 3,
  queryMode: QueryMode::DENSE,
));

$sparseResults = $index->queryData(new DataQuery(
  data: 'Upstash Vector',
  topK: 3,
  queryMode: QueryMode::SPARSE,
));

// Rerank dense and sparse results as you like here
```

</Tab>

```shell
curl $UPSTASH_VECTOR_REST_URL/query-data \
  -H "Authorization: Bearer $UPSTASH_VECTOR_REST_TOKEN" \
  -d '{"data": "Upstash Vector", "queryMode": "DENSE"}'

curl $UPSTASH_VECTOR_REST_URL/query-data \
  -H "Authorization: Bearer $UPSTASH_VECTOR_REST_TOKEN" \
  -d '{"data": "Upstash Vector", "queryMode": "SPARSE"}'
```

</Tab>

</Tabs>

# Metadata and Data
Source: https://upstash.com/docs/vector/features/metadata

## Metadata

Metadata feature allows you to store context with your vectors to make a connection.
There can be a couple of uses of this:

1. You can put the source of the vector in the metadata to use in your application from the query response.
2. You can put some metadata to further filter the results upon the query.

You can set metadata with your vector as follows:

<Tabs>

```python
from upstash_vector import Index

index = Index(
    url="UPSTASH_VECTOR_REST_URL",
    token="UPSTASH_VECTOR_REST_TOKEN",
)

index.upsert(
    [("id-0", [0.9215, 0.3897]), {"url": "https://imgur.com/z9AVZLb"}],
)
```

</Tab>

```js
import { Index } from "@upstash/vector"

const index = new Index({
  url: "UPSTASH_VECTOR_REST_URL",
  token: "UPSTASH_VECTOR_REST_TOKEN",
})

await index.upsert({
  "id": "id-0",
  vector: [0.9215, 0.3897],
  metadata: {
    url: "https://imgur.com/z9AVZLb",
  },
})
```

</Tab>

```go
package main

import (
	"github.com/upstash/vector-go"
)

func main() {
	index := vector.NewIndex("UPSTASH_VECTOR_REST_URL", "UPSTASH_VECTOR_REST_TOKEN")

index.Upsert(vector.Upsert{
		Id:       "id-0",
		Vector:   []float32{0.9215, 0.3897},
		Metadata: map[string]any{"url": "https://imgur.com/z9AVZLb"},
	})
}
```

</Tab>

```php
use Upstash\Vector\Index;
use Upstash\Vector\VectorUpsert;

use function Upstash\Vector\createRandomVector;

$index = new Index(
  url: 'UPSTASH_VECTOR_REST_URL',
  token: 'UPSTASH_VECTOR_REST_TOKEN',
);

$index->upsert(new VectorUpsert(
  id: 'id-0',
  vector: createRandomVector(384),
  metadata: [
    'url' => "https://imgur.com/z9AVZLb",
  ],
));
```

</Tab>

```shell
curl $UPSTASH_VECTOR_REST_URL/upsert \
  -X POST \
  -H "Authorization: Bearer $UPSTASH_VECTOR_REST_TOKEN" \
  -d '{
   "id":"id-0",
   "vector":[0.9215,0.3897],
   "metadata":{
      "url":"https://imgur.com/z9AVZLb"
   }
}'
```

</Tab>

</Tabs>

When you do a query or fetch, you can opt-in to retrieve the metadata as follows:

* **Query Example**

<Tabs>

```python
from upstash_vector import Index

index = Index(
    url="UPSTASH_VECTOR_REST_URL",
    token="UPSTASH_VECTOR_REST_TOKEN",
)

index.query(
    [0.9215, 0.3897],
    top_k=5,
    include_metadata=True,
)
```

</Tab>

```js
import { Index } from "@upstash/vector"

const index = new Index({
  url: "UPSTASH_VECTOR_REST_URL",
  token: "UPSTASH_VECTOR_REST_TOKEN",
})

await index.query({
  vector: [0.9215, 0.3897],
  topK: 5,
  includeMetadata: true,
})
```

</Tab>

```go
package main

import (
	"github.com/upstash/vector-go"
)

func main() {
	index := vector.NewIndex("UPSTASH_VECTOR_REST_URL", "UPSTASH_VECTOR_REST_TOKEN")

index.Query(vector.Query{
		Vector:          []float32{0.9215, 0.3897},
		TopK:            5,
		IncludeMetadata: true,
	})
}
```

</Tab>

```php
use Upstash\Vector\Index;
use Upstash\Vector\VectorQuery;

$index = new Index(
  url: 'UPSTASH_VECTOR_REST_URL',
  token: 'UPSTASH_VECTOR_REST_TOKEN',
);

$index->query(new VectorQuery(
  vector: [0.9215, 0.3897],
  topK: 5,
  includeMetadata: true,
));
```

</Tab>

```shell
curl $UPSTASH_VECTOR_REST_URL/query \
  -H "Authorization: Bearer $UPSTASH_VECTOR_REST_TOKEN" \
  -d '{
   "vector":[0.9215,0.3897],
   "topK" : 5,
   "includeMetadata": true
}'
```

</Tab>

</Tabs>

```json
{
  "result": [
    {
      "id": "id-0",
      "score": 1,
      "metadata": {
        "url": "https://imgur.com/z9AVZLb"
      }
    },
    {
      "id": "id-3",
      "score": 0.99961007,
      "metadata": {
        "url": "https://imgur.com/zfOPmnI"
      }
    }
  ]
}
```

Also, you can filter the results further by providing a metadata filter:

<Tabs>

```python
from upstash_vector import Index

index = Index(
    url="UPSTASH_VECTOR_REST_URL",
    token="UPSTASH_VECTOR_REST_TOKEN",
)

index.query(
    [0.9215, 0.3897],
    top_k=5,
    include_metadata=True,
    filter="url GLOB '*imgur.com*'",
)
```

</Tab>

```js
import { Index } from "@upstash/vector"

const index = new Index({
  url: "UPSTASH_VECTOR_REST_URL",
  token: "UPSTASH_VECTOR_REST_TOKEN",
})

await index.query({
  vector: [0.9215, 0.3897],
  topK: 5,
  includeMetadata: true,
  filter: "url GLOB '*imgur.com*'",
})
```

</Tab>

```go
package main

import (
	"github.com/upstash/vector-go"
)

func main() {
	index := vector.NewIndex("UPSTASH_VECTOR_REST_URL", "UPSTASH_VECTOR_REST_TOKEN")

index.Query(vector.Query{
		Vector:          []float32{0.9215, 0.3897},
		TopK:            5,
		IncludeMetadata: true,
		Filter:          "url GLOB '*imgur.com*'",
	})
}
```

</Tab>

```php
use Upstash\Vector\Index;
use Upstash\Vector\VectorQuery;

$index = new Index(
  url: 'UPSTASH_VECTOR_REST_URL',
  token: 'UPSTASH_VECTOR_REST_TOKEN',
);

$index->query(new VectorQuery(
  vector: [0.9215, 0.3897],
  topK: 5,
  includeMetadata: true,
  filter: "url GLOB '*imgur.com*'",
));
```

</Tab>

```shell
curl $UPSTASH_VECTOR_REST_URL/query \
  -H "Authorization: Bearer $UPSTASH_VECTOR_REST_TOKEN" \
  -d '{
   "vector":[0.9215,0.3897],
   "topK" : 5,
   "includeMetadata": true,
   "filter": "url GLOB \"*imgur.com*\""
}'
```
</Tab>

</Tabs>

See [Metadata Filtering documentation](/docs/vector/features/filtering) for more details.

* **Range Example**

<Tabs>

```python
from upstash_vector import Index

index = Index(
    url="UPSTASH_VECTOR_REST_URL",
    token="UPSTASH_VECTOR_REST_TOKEN",
)

index.range(
    cursor="0",
    limit=3,
    include_metadata=True,
)
```

</Tab>

```js
import { Index } from "@upstash/vector"

const index = new Index({
  url: "UPSTASH_VECTOR_REST_URL",
  token: "UPSTASH_VECTOR_REST_TOKEN",
})

await index.range({
  cursor: "0",
  limit: 3,
  includeMetadata: true,
})
```

</Tab>

```go
package main

import (
	"github.com/upstash/vector-go"
)

func main() {
	index := vector.NewIndex("UPSTASH_VECTOR_REST_URL", "UPSTASH_VECTOR_REST_TOKEN")

index.Range(vector.Range{
		Cursor:          "0",
		Limit:           3,
		IncludeMetadata: true,
	})
}
```

</Tab>

```php
use Upstash\Vector\Index;
use Upstash\Vector\VectorRange;

$index = new Index(
  url: 'UPSTASH_VECTOR_REST_URL',
  token: 'UPSTASH_VECTOR_REST_TOKEN',
);

$index->range(new VectorRange(
  limit: 3,
  includeMetadata: true,
));
```

</Tab>

```shell
curl $UPSTASH_VECTOR_REST_URL/range \
  -H "Authorization: Bearer $UPSTASH_VECTOR_REST_TOKEN" \
  -d '{ "cursor" : "0",  "limit" : 3, "includeMetadata": true}'
```
</Tab>

</Tabs>

```json
{
  "result": {
    "nextCursor": "4",
    "vectors": [
      { "id": "id-0", "metadata": { "url": "https://imgur.com/z9AVZLb" } },
      { "id": "id-1", "metadata": { "url": "https://imgur.com/a2nCEIt" } },
      { "id": "id-2", "metadata": { "url": "https://imgur.com/zfOPmnI" } }
    ]
  }
}
```

## Data

Data is another kind of information you can store per vector
to attribute some context to it. Compared to metadata, it is not
structured, and it can only be fetched in queries, not used
to further filter them.

It is especially useful when you upsert raw text data, so that you
would have access to the textual form of vector along with the
embedded vector values.

It can save you from storing contextual information per vector
in a separate database.

You can set both the metadata and data, or only one of them
while upserting your vectors as follows:

<Tabs>

```python
from upstash_vector import Index

index = Index(
    url="UPSTASH_VECTOR_REST_URL",
    token="UPSTASH_VECTOR_REST_TOKEN",
)

index.upsert(
    [
        {
            "id": "id-0",
            "vector": [0.9215, 0.3897],
            "metadata": {"url": "https://imgur.com/z9AVZLb"},
            "data": "data-0",
        },
        {
            "id": "id-1",
            "vector": [0.3897, 0.9215],
            "data": "data-1",
        },
    ],
)
```

</Tab>

```js
import { Index } from "@upstash/vector"

const index = new Index({
  url: "UPSTASH_VECTOR_REST_URL",
  token: "UPSTASH_VECTOR_REST_TOKEN",
})

await index.upsert([
  {
    id: "id-0",
    vector: [0.9215, 0.3897],
    metadata: {"url": "https://imgur.com/z9AVZLb"},
    data: "data-0",
  },
  {
    id: "id-1",
    vector: [0.3897, 0.9215],
    data: "data-1",
  },
])
```

</Tab>

```php
use Upstash\Vector\Index;
use Upstash\Vector\VectorUpsert;

$index = new Index(
  url: 'UPSTASH_VECTOR_REST_URL',
  token: 'UPSTASH_VECTOR_REST_TOKEN',
);

$index->upsertMany([
  new VectorUpsert(
    id: 'id-0',
    vector: [0.9215, 0.3897],
    data: 'data-0',
  ),
  new VectorUpsert(
    id: 'id-1',
    vector: [0.3897, 0.9215],
    data: 'data-1',
  ),
]);
```

</Tab>

```shell
curl $UPSTASH_VECTOR_REST_URL/upsert \
  -X POST \
  -H "Authorization: Bearer $UPSTASH_VECTOR_REST_TOKEN" \
  -d '[
        {
            "id": "id-0",
            "vector": [0.9215, 0.3897],
            "metadata": {"url": "https://imgur.com/z9AVZLb"},
            "data": "data-0"
        },
        {
            "id": "id-1",
            "vector": [0.3897, 0.9215],
            "data": "data-1"
        }
    ]'
```

</Tab>

</Tabs>

When a raw text data is upserted, the data will be set to
the raw text data automatically:

<Tabs>

```python
from upstash_vector import Index

index = Index(
    url="UPSTASH_VECTOR_REST_URL",
    token="UPSTASH_VECTOR_REST_TOKEN",
)

index.upsert(
    [
        {
            "id": "id-2",
            "data": "Upstash is a serverless data platform.",
        },
    ],
)
```

</Tab>

```js
import { Index } from "@upstash/vector"

const index = new Index({
  url: "UPSTASH_VECTOR_REST_URL",
  token: "UPSTASH_VECTOR_REST_TOKEN",
})

await index.upsert([
  {
    id: "id-2",
    data: "Upstash is a serverless data platform.",
  }
])
```

</Tab>

```php
use Upstash\Vector\Index;
use Upstash\Vector\DataUpsert;

$index = new Index(
  url: 'UPSTASH_VECTOR_REST_URL',
  token: 'UPSTASH_VECTOR_REST_TOKEN',
);

$index->upsertData(new DataUpsert(
  id: 'id-0',
  data: 'Upstash is a serverless data platform.',
));
```

</Tab>

```shell
curl $UPSTASH_VECTOR_REST_URL/upsert-data \
  -X POST \
  -H "Authorization: Bearer $UPSTASH_VECTOR_REST_TOKEN" \
  -d '{
        "id": "id-0",
        "data": "Upstash is a serverless data platform."
      }'
```

</Tab>

</Tabs>

<Tabs>

```python
from upstash_vector import Index

index = Index(
    url="UPSTASH_VECTOR_REST_URL",
    token="UPSTASH_VECTOR_REST_TOKEN",
)

result = index.query(
    data="What is Upstash?",
    include_data=True,
)

for res in result:
    print(f"{res.id}: {res.data}")
```

</Tab>

```js
import { Index } from "@upstash/vector"

const index = new Index({
  url: "UPSTASH_VECTOR_REST_URL",
  token: "UPSTASH_VECTOR_REST_TOKEN",
})

const result = await index.query({
  data: "What is Upstash?",
  includeData: true,
  topK: 3
})

for (const vector of result) {
  console.log(`${vector.id}: ${vector.data}`)
}
```

</Tab>

```php
use Upstash\Vector\Index;
use Upstash\Vector\DataQuery;

$index = new Index(
  url: 'UPSTASH_VECTOR_REST_URL',
  token: 'UPSTASH_VECTOR_REST_TOKEN',
);

$results = $index->queryData(new DataQuery(
  data: 'Upstash is a serverless data platform.',
  topK: 3
  includeData: true,
));

foreach ($results as $result) {
  print_r($result->toArray());
}
```

</Tab>

```shell
curl $UPSTASH_VECTOR_REST_URL/query-data \
  -H "Authorization: Bearer $UPSTASH_VECTOR_REST_TOKEN" \
  -d '{
        "data": "What is Upstash?",
        "includeData": true,
      }'
```

</Tab>

</Tabs>

Similar to metadata, the data field can be requested in queries, range
iterator, and fetch requests, by setting the `includeData` to `true` as
shown above.

# Namespaces
Source: https://upstash.com/docs/vector/features/namespaces

Upstash Vector allows you to partition a single index into multiple isolated namespaces. Each namespace acts as a self-contained subset of the index, and read and write requests are limited to one namespace.

Each vector index has at least one default namespace and optionally many more.

If no namespace is specified, the operations will use the default namespace, which has the name `""` (empty string).

<Note>
  Indexes created before the namespaces feature can still be used as they are,
  without modification. All operations are assumed to use the default namespace.
</Note>

## Using a Namespace

Namespaces are created implicitly when an upsert operation is performed, so there is no specific endpoint for creating a namespace.

For example, the code snippet below will create the namespace `ns` if it does not already exist, upsert and query the vector only on that namespace.

<Tabs>

```python
from upstash_vector import Index

index = Index(
    url="UPSTASH_VECTOR_REST_URL",
    token="UPSTASH_VECTOR_REST_TOKEN",
)

index.upsert(
    [("id-0", [0.9215, 0.3897])],
    namespace="ns",
)

index.query(
    [0.9215, 0.3897],
    top_k=5,
    namespace="ns",
)
```

</Tab>

```js
import { Index } from "@upstash/vector"

const index = new Index({
  url: "UPSTASH_VECTOR_REST_URL",
  token: "UPSTASH_VECTOR_REST_TOKEN",
})

const namespace = index.namespace("ns")

await namespace.upsert({
  id: "id-0",
  vector: [0.9215, 0.3897],
})

await namespace.query({
  vector: [0.9215, 0.3897],
  topK: 5,
})
```

</Tab>

```go
package main

import (
	"github.com/upstash/vector-go"
)

func main() {
	index := vector.NewIndex("UPSTASH_VECTOR_REST_URL", "UPSTASH_VECTOR_REST_TOKEN")

namespace := index.Namespace("ns")

namespace.Upsert(vector.Upsert{
		Id:     "id-0",
		Vector: []float32{0.9215, 0.3897},
	})

namespace.Query(vector.Query{
		Vector: []float32{0.9215, 0.3897},
		TopK:   5,
	})
}
```

</Tab>

```php
use Upstash\Vector\Index;
use Upstash\Vector\VectorUpsert;
use Upstash\Vector\VectorQuery;

$index = new Index(
  url: 'UPSTASH_VECTOR_REST_URL',
  token: 'UPSTASH_VECTOR_REST_TOKEN',
);

$namespace = $index->namespace('ns');

$namespace->upsert(new VectorUpsert(
  id: 'id-0',
  vector: [0.9215, 0.3897],
));

$namespace->query(new VectorQuery(
  vector: [0.9215, 0.3897],
  topK: 5,
));
```

</Tab>

```shell
curl $UPSTASH_VECTOR_REST_URL/upsert/ns \
  -X POST \
  -H "Authorization: Bearer $UPSTASH_VECTOR_REST_TOKEN" \
  -d '{"id":"id-0", "vector":[0.9215,0.3897]}'

curl $UPSTASH_VECTOR_REST_URL/query/ns \
  -H "Authorization: Bearer $UPSTASH_VECTOR_REST_TOKEN" \
  -d '{"vector":[0.9215,0.3897], "topK" : 5}'
```

</Tab>

</Tabs>

Under the hood, when using a namespace, your requests are sent to `<vector-url>/<command>/namespace-name` to only be executed only against that namespace.

## Deleting a Namespace

Namespaces can be deleted by using the
[Delete Namespace](../api/endpoints/delete-namespace) API.

<Tabs>

```python
from upstash_vector import Index

index = Index(
    url="UPSTASH_VECTOR_REST_URL",
    token="UPSTASH_VECTOR_REST_TOKEN",
)

index.delete_namespace("ns")
```

</Tab>

```js
import { Index } from "@upstash/vector"

const index = new Index({
  url: "UPSTASH_VECTOR_REST_URL",
  token: "UPSTASH_VECTOR_REST_TOKEN",
})

await index.deleteNamespace("ns")
```

</Tab>

```go
package main

import (
	"github.com/upstash/vector-go"
)

func main() {
	index := vector.NewIndex("UPSTASH_VECTOR_REST_URL", "UPSTASH_VECTOR_REST_TOKEN")

namespace := index.Namespace("ns")

namespace.DeleteNamespace()
}
```

</Tab>

```php
use Upstash\Vector\Index;

$index = new Index(
  url: 'UPSTASH_VECTOR_REST_URL',
  token: 'UPSTASH_VECTOR_REST_TOKEN',
);

$index->namespace('ns')->deleteNamespace();
```

</Tab>

```shell
curl $UPSTASH_VECTOR_REST_URL/delete-namespace/ns \
  -X DELETE \
  -H "Authorization: Bearer $UPSTASH_VECTOR_REST_TOKEN"
```

</Tab>

</Tabs>

## Listing Namespaces

All active namespaces can be listed by using the
[List Namespaces](../api/endpoints/list-namespaces) API.

<Tabs>

```python
from upstash_vector import Index

index = Index(
    url="UPSTASH_VECTOR_REST_URL",
    token="UPSTASH_VECTOR_REST_TOKEN",
)

index.list_namespaces()
```

</Tab>

```js
import { Index } from "@upstash/vector"

const index = new Index({
  url: "UPSTASH_VECTOR_REST_URL",
  token: "UPSTASH_VECTOR_REST_TOKEN",
})

await index.listNamespaces()
```

</Tab>

```go
package main

import (
	"github.com/upstash/vector-go"
)

func main() {
	index := vector.NewIndex("UPSTASH_VECTOR_REST_URL", "UPSTASH_VECTOR_REST_TOKEN")

index.ListNamespaces()
}
```

</Tab>

```php
use Upstash\Vector\Index;

$index = new Index(
  url: 'UPSTASH_VECTOR_REST_URL',
  token: 'UPSTASH_VECTOR_REST_TOKEN',
);

$index->listNamespaces();
```

</Tab>

```shell
curl $UPSTASH_VECTOR_REST_URL/list-namespaces \
  -H "Authorization: Bearer $UPSTASH_VECTOR_REST_TOKEN"
```

</Tab>

</Tabs>

# Resumable Query
Source: https://upstash.com/docs/vector/features/resumablequery

When searching for approximate nearest neighbors of a vector with regular query API,
you specify a topK so that the vector index returns at most that many results.

In regular query API, it is not possible to continue the query where it is left off, as
each query runs from start to completion, before returning a response.

However, there might be cases where you want to get the next topK many similar vectors
after running a regular query. Perhaps, you wanted to fetch the next batch of vectors
for the next page of your search functionality.

Resumable query helps you to achieve that. It has the same features as the regular query;
you can specify a filter, get values, metadata or data of the vectors, or specify a topK
value. But, after getting the initial response from the server, it allows you to query
for more, starting from where it left off instead of the start.

## Starting a Resumable Query

Each resumable query starts in this phase. Using our SDKs or the REST API, you can
initiate a resumable query. The filter or flags to include vector values, metadata,
or data will be valid for the entire duration of the resumable query.

When you start the query, the server responds with the first batch of the most
similar vectors and a handle that uniquely identifies the query so that you
can continue the query where you left off.

<Tabs>

```python
from upstash_vector import Index

index = Index(
    url="UPSTASH_VECTOR_REST_URL",
    token="UPSTASH_VECTOR_REST_TOKEN",
)

result, handle = index.resumable_query(
    vector=[0.1, 0.2],
    top_k=2,
    include_metadata=True,
)

# first batch of the results
for r in result:
    print(r)
```

</Tab>

```js
import { Index } from "@upstash/vector"

const index = new Index({
  url: "UPSTASH_VECTOR_REST_URL",
  token: "UPSTASH_VECTOR_REST_TOKEN",
});

const { result, fetchNext, stop } = await index.resumableQuery({
  vector: [0.1, 0.2],
  topK: 2,
  includeMetadata: true,
});

// first batch of the results
for (let r of result) {
  console.log(r);
}
```

</Tab>

```go
package main

import (
	"fmt"
	"log"

"github.com/upstash/vector-go"
)

func main() {
	index := vector.NewIndex(
		"UPSTASH_VECTOR_REST_URL",
		"UPSTASH_VECTOR_REST_TOKEN",
	)

scores, handle, err := index.ResumableQuery(vector.ResumableQuery{
		Vector:          []float32{0.1, 0.2},
		TopK:            2,
		IncludeMetadata: true,
	})
	if err != nil {
		log.Fatal(err)
	}

defer handle.Close()

// first batch of the results
	for _, score := range scores {
		fmt.Printf("%+v\n", score)
	}
}
```

</Tab>

```shell
curl $UPSTASH_VECTOR_REST_URL/resumable-query \
  -X POST \
  -H "Authorization: Bearer $UPSTASH_VECTOR_REST_TOKEN" \
  -d '{
    "vector": [0.1, 0.2],
    "topK": 2,
    "includeMetadata": true
  }'
```

</Tab>

</Tabs>

We support resumable queries with raw vector values as shown above,
or with raw text data for indexes created with Upstash hosted embedding models.

## Resuming the Resumable Query

Using the handle returned by the initial call to resumable query,
you can get the next batch of the most similar vectors, starting
from the last response.

You can fetch as many next batch as possible until you iterate
over the entire index.

<Tabs>

```python
# next batch of the results
next_result = handle.fetch_next(
    additional_k=3,
)

for r in next_result:
    print(r)

# it is possible to call fetch_next more than once
next_result = handle.fetch_next(
    additional_k=5,
)

for r in next_result:
    print(r)
```

</Tab>

```js
// next batch of the results
let nextResult = await fetchNext(3);

for (let r of nextResult) {
  console.log(r);
}

// it is possible to call fetch_next more than once
nextResult = await fetchNext(3);

for (let r of nextResult) {
  console.log(r);
}
```

</Tab>

```go
// next batch of the results
scores, err = handle.Next(vector.ResumableQueryNext{
	AdditionalK: 3,
})
if err != nil {
	log.Fatal(err)
}

for _, score := range scores {
	fmt.Printf("%+v\n", score)
}

// it is possible to call Next more than once
scores, err = handle.Next(vector.ResumableQueryNext{
	AdditionalK: 5,
})
if err != nil {
	log.Fatal(err)
}

for _, score := range scores {
	fmt.Printf("%+v\n", score)
}
```

</Tab>

```shell
curl $UPSTASH_VECTOR_REST_URL/resumable-query-next \
  -X POST \
  -H "Authorization: Bearer $UPSTASH_VECTOR_REST_TOKEN" \
  -d '{
    "uuid": "550e8400-e29b-41d4-a716-446655440000",
    "additionalK": 3
  }'
```

</Tab>

</Tabs>

## Stopping the Resumable Query

Each resumable query requires us to maintain a state in the server.
So, there is a limit for the maximum number of active resumable queries
at a time.

That's why it is important to stop the resumable query once you are
done with it.

Resumable queries can be stopped using the handle returned with the
initial call.

<Tabs>

```python
handle.stop()
```

</Tab>

```js
await stop();
```

</Tab>

```go
handle.Close()
```

</Tab>

```shell
curl $UPSTASH_VECTOR_REST_URL/resumable-query-end \
  -X POST \
  -H "Authorization: Bearer $UPSTASH_VECTOR_REST_TOKEN" \
  -d '{
    "uuid": "550e8400-e29b-41d4-a716-446655440000"
  }'
```

</Tab>

</Tabs>

We periodically scan resumable queries to stop the idle ones, so
queries that have not touched for some time are stopped automatically.

By default, the max idle time of a resumable query is 1 hour.
You can configure this behavior by specifying a max idle time in seconds
while starting the resumable query.

<Tabs>

```python
result, handle = index.resumable_query(
    vector=[0.1, 0.2],
    top_k=2,
    include_metadata=True,
    max_idle = 7200, # two hours, in seconds
)
```

</Tab>

```js
const { result, fetchNext, stop } = await index.resumableQuery({
  vector: [0.1, 0.2],
  topK: 2,
  includeMetadata: true,
  maxIdle: 7200, // two hours, in seconds
});
```

</Tab>

```go
scores, handle, err := index.ResumableQuery(vector.ResumableQuery{
	Vector:          []float32{0.1, 0.2},
	TopK:            2,
	IncludeMetadata: true,
	MaxIdle:         7200, // two hours, in seconds
})
```

</Tab>

</Tab>

</Tabs>

# Vector Similarity Functions
Source: https://upstash.com/docs/vector/features/similarityfunctions

When creating a vector index in Upstash Vector, you have the flexibility to choose from different vector similarity functions.
Each function yields distinct query results, catering to specific use cases. Here are the three supported similarity functions:

<Note>
  The score returned from query requests is a normalized value between 0 and 1,
  where 1 indicates the highest similarity and 0 the lowest regardless of the
  similarity function used.
</Note>

#### Cosine Similarity

Cosine similarity measures the cosine of the angle between two vectors. It is particularly useful when the magnitude of the vectors is not essential, and the focus is on the orientation.

**Use Cases:**

* **Natural Language Processing (NLP):** Ideal for comparing document embeddings or word vectors, as it captures semantic similarity irrespective of vector magnitude.
* **Recommendation Systems:** Effective in recommending items based on user preferences or content similarities.

**Score calculation:**
` (1 + cosine_similarity(v1, v2)) / 2;`

#### Euclidean Distance

Euclidean distance calculates the straight-line distance between two vectors in a multi-dimensional space. It is well-suited for scenarios where the magnitude of vectors is crucial, providing a measure of their spatial separation.

**Use Cases:**

* **Computer Vision:** Useful in image processing tasks, such as image recognition or object detection, where the spatial arrangement of features is significant.
* **Anomaly Detection:** Valuable for detecting anomalies in datasets, as it considers both the direction and magnitude of differences between vectors.

**Score calculation:**
`1 / (1 + squared_distance(v1, v2))`

#### Dot Product

The dot product measures the similarity by multiplying the corresponding components of two vectors and summing the results. It provides a measure of alignment between vectors.
Note that to use dot product, the vectors needs to be normalized to be of unit length.

**Use Cases:**

* **Machine Learning Models:** Commonly used in machine learning for tasks like sentiment analysis or classification, where feature alignment is critical.
* **Collaborative Filtering:** Effective in collaborative filtering scenarios, such as recommending items based on user behavior or preferences.

**Score calculation:**
` (1 + dot_product(v1, v2)) / 2`

# Sparse Indexes
Source: https://upstash.com/docs/vector/features/sparseindexes

Sparse vectors are representations in a high-dimensional space,
where only a small number of dimensions have non-zero values.

For example, for the same text, a dense vector representation with
the BGE-M3 model would have 1024 non-zero valued dimensions.
However, the sparse vector representation of the same text would
have less than a hundred non-zero valued dimensions, whereas vector
space potentially has more than 250 thousand dimensions. Also, unlike
dense vector representations, sparse vectors might have varying
non-zero valued dimensions depending on the text.

Generally, sparse vectors can be represented with two arrays of equal
sizes:

* The first array for the indices contains the indices of the non-zero
  dimensions.
* The second array for values contains the floating point values for
  the non-zero dimensions.

```python
dense = [0.1, 0.3, , ...thousands of non-zero values..., 0.5, 0.2]

sparse = (
    [23, 42, 5523, 123987, 240001], # some low number of dimension indices
    [0.1, 0.3, 0.1, 0.2, 0.5], # non-zero values corresponding to dimensions
)
```

Unlike dense vectors which excel at approximate semantic matching,
sparse vectors are particularly useful for tasks that require exact or
near exact matching of tokens/words/features. That makes it useful
for various tasks, such as:

* **Information Retrieval and Text Analysis**: By representing documents
  as sparse vectors where each token/word would correspond to a dimension
  in high dimensional vocabulary; and varying values by the frequencies
  of the tokens/words in the document or by weighting them with inverse
  document frequencies to favor rare terms, you can build complex
  search pipelines.
* **Recommender Systems**: By representing user interactions, preferences,
  ratings, or purchases as sparse vectors, you can identify relevant
  recommendations, and personalize content delivery.

## Creating Sparse Vectors

There are various ways to create sparse vectors. You can use
[BM25](https://en.wikipedia.org/wiki/Okapi_BM25) for information
retrieval tasks, or use models like [SPLADE](https://github.com/naver/splade)
that enhance documents and queries with term weighting and expansion.

Upstash gives you full control by allowing you to upsert and query
sparse vectors.

Also, to make embedding easier for you, Upstash provides some hosted
models and allows you to upsert and query text data. Behind the scenes,
the text data is converted to sparse vectors.

You can create your index with a sparse embedding model to use this feature.

### BGE-M3 Sparse Vectors

BGE-M3 is a multi-functional, multi-lingual, and multi-granular model
widely used for dense indexes.

We also provide BGE-M3 as a sparse vector embedder, which outputs
sparse vectors from `250_002` dimensional space.

These sparse vectors have values where each token is weighted
according to the input text, which enhances traditional sparse vectors
with contextuality.

### BM25 Sparse Vectors

BM25 is a popular algorithm used in full-text search systems to rank
documents based on their relevance to a query.

This algorithm relies on key principles of term frequency,
inverse document frequency, and document length normalization,
making it well-suited for text retrieval tasks.

* **Rare terms are important**: BM25 gives more weight to words that are
  less common in the collection of documents. For example, in a search
  for “Upstash Vector”, the word “Upstash” might be considered more
  important than “Vector” if it appears less frequently across all documents.
* **Repeating a Word Helps—But Only Up to a Point**: BM25 considers how
  often a word appears in a document, but it limits the benefit of repeating
  the word too many times. This means mentioning “Upstash” a hundred times
  won’t make a document overly important compared to one that mentions
  it just a few times.
* **Shorter Documents Often Rank Higher**: Shorter documents that match
  the query are usually more relevant. BM25 adjusts for document length
  so longer documents don’t get unfairly ranked just because they contain
  more words.

Upstash provides a general purpose BM25 algorithm, that applies to documents
and queries in English. It tokenizes the text into words, removes stop words,
stems the remaining words, and assigns a weighted value to them, based on the
BM25 formula:

```
                       IDF(qᵢ) * f(qᵢ, D) * (k₁ + 1)
BM25(D, Q) = Σ ----------------------------------------------
               f(qᵢ, D) + k₁ * (1 - b + b * (|D| / avg(|D|)))
```

Where:

* `f(qᵢ, D)` is the frequency of term `qᵢ` in document `D`.
* `|D|` is the length of document `D`.
* `avg(|D|)` is the average document length in the collection.
* `k₁` is the term frequency saturation parameter.
* `b` is the length normalization parameter.
* `IDF(qᵢ)` is the inverse document frequency of term `qᵢ`

To make it a general purpose model, we had to decide on some of the
constants mentioned above, which would differ from implementation
to implementation. We decided to use the following values for

* `k₁` = `1.2`, a widely used value in the absence of advanced optimizations
* `b` = `0.75`, a widely used value in the absence of advanced optimizations
* `avg(|D|)` = `32`, which was chosen by tokenizing and taking the average of
  [MSMARCO](https://microsoft.github.io/msmarco/) dataset vectors, rounded
  to the nearest power of two.

In the future, we might provide support for more languages and the ability to
provide different values for the above constants.

As for the inverse document frequency `IDF(qᵢ)`, we maintain that information
per token in the vector database itself. You can use it by providing it
as the weighting strategy for your queries so that you don't have to weight
it yourself.

## Using Sparse Indexes

### Upserting Sparse Vectors

You can upsert sparse vectors into Upstash Vector indexes in two different ways.

#### Upserting Sparse Vectors

You can upsert sparse vectors by representing them as two arrays of equal
sizes. One signed 32-bit integer array for non-zero dimension indices,
and one 32-bit float array for the values.

<Tabs>

```python
from upstash_vector import Index, Vector
from upstash_vector.types import SparseVector

index = Index(
    url="UPSTASH_VECTOR_REST_URL",
    token="UPSTASH_VECTOR_REST_TOKEN",
)

index.upsert(
    vectors=[
        Vector(id="id-0", sparse_vector=SparseVector([1, 2], [0.1, 0.2])),
        Vector(id="id-1", sparse_vector=SparseVector([123, 44232], [0.5, 0.4])),
    ]
)
```

</Tab>

```js
import { Index } from "@upstash/vector"

const index = new Index({
  url: "UPSTASH_VECTOR_REST_URL",
  token: "UPSTASH_VECTOR_REST_TOKEN",
})

await index.upsert([{
  id: 'id-0',
  sparseVector: {
    indices: [2, 3],
    values: [0.13, 0.87],
  },
}])
```

</Tab>

```go
package main

import (
	"github.com/upstash/vector-go"
)

func main() {
	index := vector.NewIndex(
		"UPSTASH_VECTOR_REST_URL",
		"UPSTASH_VECTOR_REST_TOKEN",
	)

err := index.UpsertMany([]vector.Upsert{
		{
			Id: "id-0",
			SparseVector: &vector.SparseVector{
				Indices: []int32{1, 2},
				Values:  []float32{0.1, 0.2},
			},
		},
		{
			Id: "id-1",
			SparseVector: &vector.SparseVector{
				Indices: []int32{123, 44232},
				Values:  []float32{0.5, 0.4},
			},
		},
	})
}
```

</Tab>

```php
use Upstash\Vector\Index;
use Upstash\Vector\VectorUpsert;
use Upstash\Vector\SparseVector;

$index = new Index(
  url: 'UPSTASH_VECTOR_REST_URL',
  token: 'UPSTASH_VECTOR_REST_TOKEN',
);

$index->upsertMany([
  new VectorUpsert(
    id: 'id-0',
    sparseVector: new SparseVector(
      indices: [1, 2],
      values: [0.1, 0.2],
    ),
  ),
  new VectorUpsert(
    id: 'id-1',
    sparseVector: new SparseVector(
      indices: [123, 44232],
      values: [0.5, 0.4],
    ),
  ),
]);
```

</Tab>

```shell
curl $UPSTASH_VECTOR_REST_URL/upsert \
  -H "Authorization: Bearer $UPSTASH_VECTOR_REST_TOKEN" \
  -d '[
    {"id": "id-0", "sparseVector": {"indices": [1, 2], "values": [0.1, 0.2]}},
    {"id": "id-1", "sparseVector": {"indices": [123, 44232], "values": [0.5, 0.4]}}
  ]'
```

</Tab>

</Tabs>

Note that, we do not allow sparse vectors to have more than `1_000` non-zero valued dimension.

#### Upserting Text Data

If you created the sparse index with an Upstash-hosted sparse embedding model,
you can upsert text data, and Upstash can embed it behind the scenes.

<Tabs>

```python
from upstash_vector import Index, Vector

index = Index(
    url="UPSTASH_VECTOR_REST_URL",
    token="UPSTASH_VECTOR_REST_TOKEN",
)

index.upsert(
    vectors=[
        Vector(id="id-0", data="Upstash Vector provides sparse embedding models."),
        Vector(id="id-1", data="You can upsert text data with these embedding models."),
    ]
)
```

</Tab>

```js
import { Index } from "@upstash/vector"

const index = new Index({
  url: "UPSTASH_VECTOR_REST_URL",
  token: "UPSTASH_VECTOR_REST_TOKEN",
})

await index.upsert([
  {
    id: 'id-0',
    data: "Upstash Vector provides dense and sparse embedding models.",
  }
])
```

</Tab>

```go
package main

import (
	"github.com/upstash/vector-go"
)

func main() {
	index := vector.NewIndex(
		"UPSTASH_VECTOR_REST_URL",
		"UPSTASH_VECTOR_REST_TOKEN",
	)

err := index.UpsertDataMany([]vector.UpsertData{
		{
			Id:   "id-0",
			Data: "Upstash Vector provides sparse embedding models.",
		},
		{
			Id:   "id-1",
			Data: "You can upsert text data with these embedding models.",
		},
	})
}
```

</Tab>

```php
use Upstash\Vector\Index;
use Upstash\Vector\DataUpsert;

$index = new Index(
  url: 'UPSTASH_VECTOR_REST_URL',
  token: 'UPSTASH_VECTOR_REST_TOKEN',
);

$index->upsertDataMany([
  new DataUpsert(
    id: 'id-0',
    data: 'Upstash Vector provides sparse embedding models.',
  ),
  new DataUpsert(
    id: 'id-1',
    data: 'You can upsert text data with these embedding models.',
  ),
]);
```

</Tab>

```shell
curl $UPSTASH_VECTOR_REST_URL/upsert-data \
  -H "Authorization: Bearer $UPSTASH_VECTOR_REST_TOKEN" \
  -d '[
    {"id": "id-0", "data": "Upstash Vector provides sparse embedding models."},
    {"id": "id-1", "data": "You can upsert text data with these embedding models."}
  ]'
```

</Tab>

</Tabs>

### Querying Sparse Vectors

Similar to upserts, you can query sparse vectors in two different ways.

#### Querying with Sparse Vectors

You can query sparse vectors by representing the sparse query vector
as two arrays of equal sizes. One signed 32-bit integer array for
non-zero dimension indices, and one 32-bit float array for the values.

We use the inner product similarity metric while calculating the
similarity scores, only considering the matching non-zero valued
dimension indices between the query vector and the indexed vectors.

<Tabs>

```python
from upstash_vector import Index
from upstash_vector.types import SparseVector

index = Index(
    url="UPSTASH_VECTOR_REST_URL",
    token="UPSTASH_VECTOR_REST_TOKEN",
)

index.query(
    sparse_vector=SparseVector([3, 5], [0.3, 0.5]),
    top_k=5,
    include_metadata=True,
)
```

</Tab>

```js
import { Index } from "@upstash/vector"

const index = new Index({
  url: "UPSTASH_VECTOR_REST_URL",
  token: "UPSTASH_VECTOR_REST_TOKEN",
})

await index.query(
  {
    sparseVector: {
      indices: [2, 3],
      values: [0.13, 0.87],
    },
    includeData: true,
    topK: 3,
  },
)
```
</Tab>

```go
package main

import (
	"github.com/upstash/vector-go"
)

func main() {
	index := vector.NewIndex(
		"UPSTASH_VECTOR_REST_URL",
		"UPSTASH_VECTOR_REST_TOKEN",
	)

scores, err := index.Query(vector.Query{
		SparseVector: &vector.SparseVector{
			Indices: []int32{3, 5},
			Values:  []float32{0.3, 05},
		},
		TopK:            5,
		IncludeMetadata: true,
	})
}
```

</Tab>

```php
use Upstash\Vector\Index;
use Upstash\Vector\VectorQuery;
use Upstash\Vector\SparseVector;

$index = new Index(
  url: 'UPSTASH_VECTOR_REST_URL',
  token: 'UPSTASH_VECTOR_REST_TOKEN',
);

$index->query(new VectorQuery(
  sparseVector: new SparseVector(
    indices: [3, 5],
    values: [0.3, 0.5],
  ),
  topK: 5,
  includeMetadata: true,
));
```

</Tab>

```shell
curl $UPSTASH_VECTOR_REST_URL/query \
  -H "Authorization: Bearer $UPSTASH_VECTOR_REST_TOKEN" \
  -d '{"sparseVector": {"indices": [3, 5], "values": [0.3, 0.5]}, "topK": 5, "includeMetadata": true}'
```

</Tab>

</Tabs>

Note that, the similarity scores are exact, not approximate. So, if there
are no vectors with one or more matching non-zero valued dimension indices with
the query vector, the result might be less than the provided top-K value.

#### Querying with Text Data

If you created the sparse index with an Upstash-hosted sparse embedding model,
you can query with text data, and Upstash can embed it behind the scenes
before performing the actual query.

<Tabs>

```python
from upstash_vector import Index

index = Index(
    url="UPSTASH_VECTOR_REST_URL",
    token="UPSTASH_VECTOR_REST_TOKEN",
)

index.query(
    data="Upstash Vector",
    top_k=5,
)
```

</Tab>

```js
import { Index } from "@upstash/vector"

const index = new Index({
  url: "UPSTASH_VECTOR_REST_URL",
  token: "UPSTASH_VECTOR_REST_TOKEN",
})

await index.query(
  {
    data: "Upstash Vector",
    topK: 1,
  },
)
```

</Tab>

```go
package main

import (
	"github.com/upstash/vector-go"
)

func main() {
	index := vector.NewIndex(
		"UPSTASH_VECTOR_REST_URL",
		"UPSTASH_VECTOR_REST_TOKEN",
	)

scores, err := index.QueryData(vector.QueryData{
		Data: "Upstash Vector",
		TopK: 5,
	})
}
```

</Tab>

```php
use Upstash\Vector\Index;
use Upstash\Vector\DataQuery;

$index = new Index(
  url: 'UPSTASH_VECTOR_REST_URL',
  token: 'UPSTASH_VECTOR_REST_TOKEN',
);

$index->queryData(new DataQuery(
  data: 'Upstash Vector',
  topK: 5,
));
```

</Tab>

```shell
curl $UPSTASH_VECTOR_REST_URL/query-data \
  -H "Authorization: Bearer $UPSTASH_VECTOR_REST_TOKEN" \
  -d '{"data": "Upstash Vector", "topK": 5}'
```

</Tab>

</Tabs>

#### Weighting Query Values

For algorithms like BM25, it is important to take the inverse
document frequencies that make matching rare terms more important
into account. It might be tricky to maintain that information
yourself, so Upstash Vector provides it out of the box. To make use
of IDF in your queries, you can pass it as a weighting strategy.

Since this is mainly meant to be used with BM25 models, the IDF
is defined as:

```
IDF(qᵢ) = log((N - n(qᵢ) + 0.5) / (n(qᵢ) + 0.5))
```

* `N` is the total number of documents in the collection.
* `n(qᵢ)` is the number of documents containing term `qᵢ`.

<Tabs>

```python
from upstash_vector import Index
from upstash_vector.types import WeightingStrategy

index = Index(
    url="UPSTASH_VECTOR_REST_URL",
    token="UPSTASH_VECTOR_REST_TOKEN",
)

index.query(
    data="Upstash Vector",
    top_k=5,
    weighting_strategy=WeightingStrategy.IDF,
)
```

</Tab>

```js
import { Index, WeightingStrategy } from "@upstash/vector";

const index = new Index({
  url: "UPSTASH_VECTOR_REST_URL",
  token: "UPSTASH_VECTOR_REST_TOKEN",
});

await index.query({
  sparseVector: {
    indices: [2, 3],
    values: [0.13, 0.87],
  },
  weightingStrategy: WeightingStrategy.IDF,
  topK: 3,
});
```
</Tab>

```go
package main

import (
	"github.com/upstash/vector-go"
)

func main() {
	index := vector.NewIndex(
		"UPSTASH_VECTOR_REST_URL",
		"UPSTASH_VECTOR_REST_TOKEN",
	)

scores, err := index.QueryData(vector.QueryData{
		Data:              "Upstash Vector",
		TopK:              5,
		WeightingStrategy: vector.WeightingStrategyIDF,
	})
}
```

</Tab>

```php
use Upstash\Vector\Index;
use Upstash\Vector\DataQuery;
use Upstash\Vector\Enums\WeightingStrategy;

$index = new Index(
  url: 'UPSTASH_VECTOR_REST_URL',
  token: 'UPSTASH_VECTOR_REST_TOKEN',
);

$index->queryData(new DataQuery(
  data: 'Upstash Vector',
  topK: 5,
  weightingStrategy: WeightingStrategy::INVERSE_DOCUMENT_FREQUENCY,
));
```

</Tab>

```shell
curl $UPSTASH_VECTOR_REST_URL/query-data \
  -H "Authorization: Bearer $UPSTASH_VECTOR_REST_TOKEN" \
  -d '{"data": "Upstash Vector", "topK": 5, "weightingStrategy": "IDF"}'
```

</Tab>

</Tabs>

# FAQ
Source: https://upstash.com/docs/vector/help/faq

**Account and Usage:**

* **What is the maximum number of indexes I can create in my account?**

You can create up to 10 indexes per account. For additional needs, please send us an email to  support@upstash.com

* **What is the maximum dimension I can set for my indexes?**

For the free tier, the maximum dimension can be 1536, for fixed and pay as you go tiers, this can be 3072, and for the pro tier, this can go up to 5376

* **How do you calculate the storage to be charged?**

Storage is a sum of vector storage, metadata, and data storage. Vector storage depends on the number of dimensions and the number of vectors in that index. Each dimension is estimated to be 4 bytes, resulting in vector storage being calculated as vector count * dimension count * 4 bytes. For metadata and data storage, it is calculated based on the vector count in an index multiplied by the average metadata and data size, which can be up to 48 Kbytes and 1 Mbytes respectively.

* **What happens when I exceed my Metadata / Data Storage limit?**

Metadata / Data Storage has a soft limit, and you will receive an email reminder to optimize your index for optimal performance if you approach this limit. The storage cost remains at $0.25 per GB. For enhanced performance, we recommend upgrading to Pro tier that meets your requirements, which includes incremental metadata and data storage

* **What happens when I exceed bandwidth limit of 200GB?**

When you exceed the 200GB monthly bandwidth limit, you will be charged at $0.03 per GB for the additional usage. The initial 200GB is provided free of charge.

* **If I upload my dataset for pay as you go tier and don’t have any read/write operation during the month, how much will I pay?**

You will only be charged for the storage of your index and metadata at a rate of $0.25 per GB. There are no hourly charges for having an index created on Upstash

* **How do you count Updates and Queries for billing purposes?**

We charge $0.40 per 100,000 operations, which includes ranges, queries, fetches, upserts and deletes, all counted equally. Ranges, Queries and Fetches are all categorized as query type of operation, whereas Upserts and Deletes are counted as updates. If upsert and delete operations involve multiple vectors at a time, the billable request count will be equal to number of vectors upserted or deleted at one request.

* **If an update/query return or insert multiple vectors at a time, will each vector be counted as separate operations or will that be counted as one operation for billing purposes?**

For the query type of operations, irrespective of the number of vectors involved in it, we count the operation as one and bill accordingly. For example, a fetch operation can return 10 vectors, and this will be counted only as 1 operation for billing purposes. However for update operations (upsert and delete), number of vectors involved in the operations is reflected as billable request count. For example a batch upsert of 1000 vectors is counted as 1000 billable request.

* **What is the maximum number of vectors I can have in an index?**

The maximum number of vectors in an index depends on the dimension size. Every plan has a max vector*dimension limit. For pay as you go tier, this limit is set at 2 billion. For instance, under this plan a user can have an index with a size of 5 million vectors and a vector dimension of 400. For details about the limits of each plan, check our pricing page.

**Functionality:**

* **Do you support hybrid search?**

We don’t support hybrid search at the moment. Although this is in our roadmap we still haven’t finalized the approach to help our users eliminate the need to have a secondary database for better search result. As we define our approach on implementing hybrid search and gather more user feedback, we will share this through our blog posts

* **Can I filter by metadata?**

Yes, see [Metadata Filtering](../features/filtering).

* **Do you support replication?**

Replication is not supported in the current release, but we are actively working on including it in our upcoming release.

* **If I do not specify a UUID during adding vectors, will Upstash Vector create one automatically?**

No, ID field is required and cannot be an empty string while inserting vectors to your index

**Data Management:**

* **How can I upload a large dataset quickly?**

You can perform batch inserts to upload datasets more efficiently. You don't need a separate batch specific operation to insert multiple vectors. The 'upsert' operation accepts either a single vector or an array of vectors. We recommend using an array size of up to 1000 for efficient batch inserts. For more details, please refer to the documentation

* **How can I remove a metadata field from a vector?**

You need to run Upsert function on the same vector ID to remove existing metadata fields from a vector. Check our  documentation on using `Upsert`,

**Infrastructure and Availability:**

* **Which cloud provider is Upstash Vector hosted on?**

Upstash is currently offered on AWS. We have plans to expand it to other cloud providers, please reach out support@upstash.com to raise this request as this will help us prioritize accordingly.

* **In what regions is Upstash available?**

Upstash Vector is currently available in two regions; AWS us-east1 and AWS eu-west-1. We are in the process of expanding to more regions where other Upstash products are currently offered.

* **Should I be on AWS to be able to use Upstash Vector?**

No. Your client can be anywhere but the clients in AWS regions will give you better performance.

**Feature Request and Upgrade:**

* **How can I request a feature during this beta release?**

Please reach out to support@upstash.com. You can also raise your feature request through our chatbot, located at the bottom of Upstash page. The chatbot will guide you through the process of submitting your feature request.

* **How to upgrade from free tier to pay-as-you-go tier?**

To upgrade from the free tier to the pay-as-you-go tier, simply enter your credit card information. This will automatically upgrade your account to the pay-as-you-go tier, allowing you to take advantage of the additional features and capabilities.

# Vercel AI SDK with Upstash Vector
Source: https://upstash.com/docs/vector/integrations/ai-sdk

The [AI SDK](https://sdk.vercel.ai/docs/introduction) is a TypeScript toolkit designed to help developers build AI-powered applications using React, Next.js, Vue, Svelte, Node.js, and more.

Upstash Vector integrates with the AI SDK to provide AI applications with the benefits of vector databases, enabling applications to perform semantic search and RAG (Retrieval-Augmented Generation).

In this guide, we’ll build a RAG chatbot using the AI SDK. This chatbot will be able to both store and retrieve information from a knowledge base. We’ll use Upstash Vector as our vector database, and the OpenAI API to generate responses.

## Prerequisites

Before getting started, make sure you have:

* An Upstash account (to upsert and query data)
* An OpenAI API key (to generate responses and embeddings)

## Setup and Installation

We will start by bootstrapping a Next.js application with the following command:

```bash
npx create-next-app rag-chatbot --typescript
cd rag-chatbot
```

Next, we will install the required packages using the following command:

<CodeGroup>
```bash npm
npm install @ai-sdk/openai ai zod @upstash/vector
```

```bash pnpm
pnpm install @ai-sdk/openai ai zod @upstash/vector
```

```bash bun
bun install @ai-sdk/openai ai zod @upstash/vector
```
</CodeGroup>

We need to set the following environment variables in our `.env` file:

```bash
OPENAI_API_KEY=your_openai_api_key
UPSTASH_VECTOR_REST_URL=your_upstash_url
UPSTASH_VECTOR_REST_TOKEN=your_upstash_token
```

You can get your Upstash credentials after creating a Vector Index in the [Upstash Console](https://console.upstash.com).

<Info>
If you are going to use Upstash hosted embedding models, you should select one of the available options when creating your index. If you are going to use custom embedding models, you should specify the dimensions of your embedding model.
</Info>

## Implementation

**RAG (Retrieval-Augmented Generation)** is the process of enabling the model to respond with information outside of its training data by embedding a user's query, retrieving the relevant source material (chunks) with the highest semantic similarity, and then passing them alongside the initial query as context.

Let's consider a simple example. Initially, a chatbot doesn't know who your favorite basketball player is. During a conversation, I inform the chatbot that my favorite player is Alperen Sengun, and it stores this information in its knowledge base. Later, in another conversation, when I ask, "Who is my favorite basketball player?" the chatbot retrieves this information from the knowledge base and responds with "Alperen Sengun."

### Chunking + Embedding Logic

**Embeddings** are a way to represent the semantic meaning of words and phrases. The larger the input to your embedding, the lower the quality the embedding will be. So, how should we approach long inputs?

One approach would be to use **chunking**. Chunking refers to the process of breaking down a particular source material into smaller pieces. Once your source material is appropriately chunked, you can embed each one and then store the embedding and the chunk together in a database (Upstash Vector in our case).

Using Upstash Vector, you can upsert embeddings generated from a custom embedding model, or you can directly upsert data, and Upstash Vector will generate embeddings for you.

In this guide, we demonstrate both methods—using Upstash-hosted embedding models and using a custom embedding model (e.g., OpenAI).

### Using Upstash Hosted Embedding Models

```typescript lib/ai/upstashVector.ts
import { Index } from '@upstash/vector'

// Configure Upstash Vector client
// Make sure UPSTASH_VECTOR_REST_URL and UPSTASH_VECTOR_REST_TOKEN are in your .env
const index = new Index({
  url: process.env.UPSTASH_VECTOR_REST_URL!,
  token: process.env.UPSTASH_VECTOR_REST_TOKEN!,
})

// Chunking logic: split on period
function generateChunks(input: string): string[] {
  return input
    .trim()
    .split('.')
    .filter(i => i !== '')
}

// Upsert
export async function upsertEmbedding(resourceId: string, content: string) {
  const chunks = generateChunks(content)

// Convert each chunk into an Upstash upsert object
  const toUpsert = chunks.map((chunk, i) => ({
    id: `${resourceId}-${i}`,
    data: chunk, // Using the data field instead of vector because embeddings are generated by Upstash
    metadata: {
      resourceId,
      content: chunk, // Store the chunk as metadata to use during response generation
    },
  }))

await index.upsert(toUpsert)
}

// Query
export async function findRelevantContent(query: string, k = 4) {
  const result = await index.query({
    data: query, // Again, using the data field instead of vector field
    topK: k,
    includeMetadata: true, // Fetch metadata as well
  })

return result
}
```

So, in this file, we create a function to upsert data into our index, and another function to query our index. While upserting data, we chunk the content into smaller pieces and store those chunks in our index.

This approach is a lot simpler compared to using a custom embedding model, because we don't need to generate embeddings ourselves, Upstash does it for us.

### Using a Custom Embedding Model

Now, let's look at how we can use a custom embedding model. We will use OpenAI's `text-embedding-ada-002` embedding model.

```typescript lib/ai/upstashVector.ts
import { Index } from '@upstash/vector'
import { embed, embedMany } from 'ai'
import { openai } from '@ai-sdk/openai'

// Configure Upstash Vector client
const index = new Index({
  url: process.env.UPSTASH_VECTOR_REST_URL!,
  token: process.env.UPSTASH_VECTOR_REST_TOKEN!,
})

// Chunking logic: split on period
function generateChunks(input: string): string[] {
  return input
    .trim()
    .split('.')
    .filter(i => i !== '')
}

// Define the embedding model
const embeddingModel = openai.embedding('text-embedding-ada-002')

// Function to generate a single embedding
async function generateEmbedding(value: string): Promise<number[]> {
  const input = value.replaceAll('\\n', ' ')
  const { embedding } = await embed({
    model: embeddingModel,
    value: input,
  })
  return embedding
}

// Function to generate embeddings for multiple chunks
async function generateEmbeddings(
  value: string,
): Promise<Array<{ content: string; embedding: number[] }>> {
  const chunks = generateChunks(value)
  const { embeddings } = await embedMany({
    model: embeddingModel,
    values: chunks,
  })
  return embeddings.map((vector, i) => ({
    content: chunks[i],
    embedding: vector,
  }))
}

// Upsert
export async function upsertEmbeddings(resourceId: string, content: string) {
  // Generate embeddings for each chunk
  const chunkEmbeddings = await generateEmbeddings(content)
  // Convert each chunk into an Upstash upsert object
  const toUpsert = chunkEmbeddings.map((chunk, i) => ({
    id: `${resourceId}-${i}`, // e.g. "abc123-0"
    vector: chunk.embedding,
    metadata: {
      resourceId,
      content: chunk.content,
    },
  }))

await index.upsert(toUpsert)
}

// Query
export async function findRelevantContent(query: string, k = 4) {
  const userEmbedding = await generateEmbedding(query)
  const result = await index.query({
    vector: userEmbedding,
    topK: k,
    includeMetadata: true,
  })

return result
}
```

In this approach, we need to generate embeddings ourselves, which is an extra step. But the advantage is that we can use any embedding model we want.

OpenAI's `text-embedding-ada-002` generates embeddings with 1536 dimensions, so the index we created must have 1536 dimensions.

## Create Resource Server Action

We will create a server action to create a new resource and upsert it to the index. This will be used by our chatbot to store information.

```typescript lib/actions/resources.ts
'use server'

import { z } from 'zod'
import { upsertEmbeddings } from '@/lib/ai/upstashVector'

// A simple schema for incoming resource content
const NewResourceSchema = z.object({
  content: z.string().min(1),
})

// Server action to parse the input and upsert to the index
export async function createResource(input: { content: string }) {
  const { content } = NewResourceSchema.parse(input)

// Generate a random ID
  const resourceId = crypto.randomUUID()

// Upsert the chunks/embeddings to Upstash Vector
  await upsertEmbeddings(resourceId, content)

return `Resource ${resourceId} created and embedded.`
}
```

## Chat API route

This route will act as the “backend” for our chatbot. The Vercel AI SDK’s useChat hook will, by default, POST to `/api/chat` with the conversation state. We’ll define that route and specify the AI model, system instructions, and any tools we’d like the model to use.

```typescript app/api/chat/route.ts
import { openai } from '@ai-sdk/openai'
import { streamText, tool } from 'ai'
import { z } from 'zod'

// Tools
import { createResource } from '@/lib/actions/resources'
import { findRelevantContent } from '@/lib/ai/upstashVector'

// Allow streaming responses up to 30 seconds
export const maxDuration = 30

export async function POST(req: Request) {
  const { messages } = await req.json()

const result = streamText({
    // 1. Choose your AI model
    model: openai('gpt-4o'),

// 2. Pass along the conversation messages from the user
    messages,

// 3. Prompt the model
    system: `You are a helpful RAG assistant.
    You have the ability to add and retrieve content from your knowledge base.
    Only respond to the user with information found in your knowledge base.
    If no relevant information is found, respond with: "Sorry, I don't know."`,

// 4. Provide your "tools": resource creation & retrieving content
    tools: {
      addResource: tool({
        description: `Add new content to the knowledge base.`,
        parameters: z.object({
          content: z.string().describe('The content to embed and store'),
        }),
        execute: async ({ content }) => {
          const msg = await createResource({ content })
          return msg
        },
      }),
      getInformation: tool({
        description: `Retrieve relevant knowledge from your knowledge base to answer user queries.`,
        parameters: z.object({
          question: z.string().describe('The question to search for'),
        }),
        execute: async ({ question }) => {
          const hits = await findRelevantContent(question)
          // Return array of metadata for each chunk
          // e.g. [{ id, score, metadata: { resourceId, content }}, ... ]
          return hits
        },
      }),
    },
  })

// 5. Return the streaming response
  return result.toDataStreamResponse()
}
```

## Chat UI

Finally, we will implement our chat UI on the home page. We will use the Vercel AI SDK’s `useChat` hook to render the chat UI. By default, the Vercel AI SDK will POST to `/api/chat` on submit.

```typescript app/page.tsx
'use client'

import { useChat } from 'ai/react'

export default function Home() {
  // This hook handles message state + streaming from /api/chat
  const { messages, input, handleInputChange, handleSubmit } = useChat({
    // You can enable multi-step calls if you want the model to call multiple tools in one session
    maxSteps: 3,
  })

return (
    <div className="mx-auto max-w-md py-6">
      <h1 className="text-xl font-bold mb-4">RAG Chatbot with Upstash Vector</h1>

{/* Render messages */}
      <div className="space-y-2 mb-8">
        {messages.map(m => (
          <div key={m.id} className="border p-2 rounded">
            <strong>{m.role}:</strong>
            <div>
              {/* If the model calls a tool, show which tool it called */}
              {m.content.length > 0 ? (
                m.content
              ) : (
                <i>calling tool: {m?.toolInvocations?.[0]?.toolName}</i>
              )}
            </div>
          </div>
        ))}
      </div>

{/* Text input */}
      <form onSubmit={handleSubmit} className="flex gap-2">
        <input
          className="flex-1 border rounded px-2 py-1"
          placeholder="Say something..."
          value={input}
          onChange={handleInputChange}
        />
        <button className="px-4 py-1 bg-black text-white rounded" type="submit">
          Send
        </button>
      </form>
    </div>
  )
}
```

## Run the Chatbot

Now, we can run our chatbot with the following command:

```bash
npm run dev
```

Here is a screenshot of the chatbot in action:

<img />

If you would like to see the entire code of a slightly revised version of this chatbot, you can check out the [GitHub repository](https://github.com/Abdusshh/rag-chatbot-ai-sdk). In this version, the user chooses which embedding model to use through the UI.

## Conclusion

Congratulations! You have successfully created a RAG chatbot that uses Upstash Vector to store and retrieve information. To learn more about Upstash Vector, please visit the [Upstash Vector documentation](/docs/vector).

To learn more about the AI SDK, visit the [Vercel AI SDK documentation](https://sdk.vercel.ai/docs/introduction). While creating this tutorial, we used the [RAG Chatbot guide](https://sdk.vercel.ai/docs/guides/rag-chatbot) created by Vercel, which uses PostgreSQL with pgvector as a vector database. Make sure to check it out if you want to learn how to create a RAG chatbot using pgvector.

# Flowise with Upstash Vector and Redis
Source: https://upstash.com/docs/vector/integrations/flowise

Flowise is an open source low-code tool for developers to build customized LLM orchestration flows & AI agents. With Upstash Vector and Upstash Redis, you can extend your Flowise flows to include semantic search, caching, and conversation memory.

## Install

To get started, you can install Flowise locally using npm. Run:

```bash
npm install -g flowise
```
Start Flowise:

```bash
npx flowise start
```

Open: http://localhost:3000

You also need to set up Upstash services:
1. Create a **Vector Index** in the [Upstash Console](https://console.upstash.com/vector). To learn more about index creation, you can check out [this page](https://docs.upstash.com/vector/overall/getstarted).
2. Create a **Redis Database** in the [Upstash Console](https://console.upstash.com/redis). To learn more about Redis database creation, you can check out [this page](/docs/redis/overall/getstarted).

## Nodes Overview

Flowise supports multiple Upstash integrations. Below are the nodes and their functionalities:

### 1. Upstash Vector Node

Use the **Upstash Vector** node to perform semantic search and store document embeddings. Connect the node to document loaders and embedding components for indexing and querying.

### 2. Upstash Redis Cache Node

The **Upstash Redis Cache** node caches LLM responses in a serverless Redis database.

### 3. Upstash Redis-Backed Chat Memory Node

The **Upstash Redis-Backed Chat Memory** node summarizes conversations and stores the memory in Redis. This enables persistent, context-aware interactions across multiple sessions.

## Example Flow

Below is an example flow using Upstash Vector:

<img />

## Learn More

For more details, visit the [Flowise documentation](https://docs.flowiseai.com/).

# LangChain with Upstash Vector
Source: https://upstash.com/docs/vector/integrations/langchain

You can use LangChain with Upstash Vector to perform semantic search and manage vector embeddings. LangChain is a powerful framework that integrates with vector databases, including Upstash Vector, making it easy to build intelligent applications.

First, we need to create a Vector Index in the [Upstash Console](https://console.upstash.com). To learn more about index creation, you can check out [this page](https://docs.upstash.com/vector/overall/getstarted).

## Install

```bash
pip install upstash-vector langchain langchain-community python-dotenv
```

## Usage

```python
from dotenv import load_dotenv
from langchain_community.vectorstores.upstash import UpstashVectorStore
from langchain.schema import Document

# Load environment variables
load_dotenv()

# Create a vector store instance
store = UpstashVectorStore(
    embedding=True,  # Embedding option enabled
)

# Sample documents to upload
documents = [
    Document(page_content="Upstash Vector is a scalable vector database."),
    Document(page_content="LangChain is a framework for building intelligent apps."),
    Document(page_content="Semantic search enables advanced query matching."),
]

# Add documents to the Upstash Vector index
store.add_documents(documents)

# Perform a similarity search
query = "What is LangChain?"
results = store.similarity_search(query, k=3)

print("Similarity Search Results:")
for res in results:
    print(res.page_content)
```

### Query Results

```plaintext
Similarity Search Results:
LangChain is a framework for building intelligent apps.
Semantic search enables advanced query matching.
Upstash Vector is a scalable vector database.
```

## Features

**Semantic Search**: Retrieve the most contextually relevant results using embeddings and vector similarity.

**Namespace Support**: Separate documents into different namespaces for better organization.

**Metada Filtering**: Metadata can be used to filter the results of a query.

## Notes

* Upstash Vector supports custom embeddings; you can specify an embedding model when initializing `UpstashVectorStore`.
* Use `.env` files to manage your Upstash credentials for secure and reusable configuration.

To learn more, visit the [LangChain documentation](https://python.langchain.com/docs/integrations/vectorstores/upstash/).

# Langflow with Upstash Vector
Source: https://upstash.com/docs/vector/integrations/langflow

Langflow provides an intuitive, visual interface to design LLM workflows. You can seamlessly integrate Upstash Vector into your Langflow projects to enable vector-based semantic search and context retrieval.

<img />

## Install

To get started, install Langflow and Upstash Vector locally or use the Langflow dashboard from [DataStax](https://www.datastax.com/products/langflow). For local installation, run:

```bash
pip install langflow upstash-vector
```

## Usage

### Creating an Upstash Vector Index

Visit the [Upstash Console](https://console.upstash.com/vector) to create a vector index. To learn more about index creation, you can check out [this page](https://docs.upstash.com/vector/overall/getstarted).

### Adding Upstash Vector to Langflow

In Langflow, you can integrate Upstash Vector for document indexing and semantic search. Use the following steps:

1. Create a workflow with the **File**, **Split**, and **Upstash** components to process and store documents in the Upstash Vector index.
2. Perform a vector search by connecting the **Upstash** component to your query input.

<img />

### Example Workflow

Enhance your chatbot by combining Langflow’s OpenAI integration with Upstash Vector. Create a RAG workflow to retrieve relevant context from your index and use it to answer user queries.

<img />

## Learn More

For a detailed guide on building a RAG chatbot with Langflow and Upstash Vector, check out this [blog post](https://upstash.com/blog/langflow-upstash-vector).

# LlamaIndex with Upstash Vector
Source: https://upstash.com/docs/vector/integrations/llamaindex

You can use LlamaIndex with Upstash Vector to perform Retrieval-Augmented Generation (RAG). LlamaIndex is a powerful tool that integrates seamlessly with vector databases like Upstash Vector, enabling advanced query and response capabilities.

## Install

```bash
pip install llama-index upstash-vector llama-index-vector-stores-upstash python-dotenv
```

## Setup

First, create a Vector Index in the [Upstash Console](https://console.upstash.com). Configure the index with:
* **Dimensions**: 1536
* **Distance Metric**: Cosine

Once the index is created, copy the `UPSTASH_VECTOR_REST_URL` and `UPSTASH_VECTOR_REST_TOKEN` and add them to your `.env` file along with your OpenAI API key:

```
UPSTASH_VECTOR_REST_URL=your_upstash_url
UPSTASH_VECTOR_REST_TOKEN=your_upstash_token
OPENAI_API_KEY=your_openai_api_key
```

## Usage

Here’s how you can integrate LlamaIndex with Upstash Vector:

```python
from llama_index.core import VectorStoreIndex, SimpleDirectoryReader
from llama_index.vector_stores.upstash import UpstashVectorStore
from llama_index.core import StorageContext
import os
from dotenv import load_dotenv

# Load environment variables
load_dotenv()

# Set OpenAI API key
openai.api_key = os.environ["OPENAI_API_KEY"]

# Initialize Upstash Vector store
upstash_vector_store = UpstashVectorStore(
    url=os.environ["UPSTASH_VECTOR_REST_URL"],
    token=os.environ["UPSTASH_VECTOR_REST_TOKEN"],
)

# Load documents using SimpleDirectoryReader
documents = SimpleDirectoryReader("./documents/").load_data()

# Create a storage context and initialize the index
storage_context = StorageContext.from_defaults(vector_store=upstash_vector_store)
index = VectorStoreIndex.from_documents(
    documents, storage_context=storage_context
)
```

## Querying

Once the index is created, you can query it to retrieve and generate responses based on document content.

```python
# Initialize the query engine
query_engine = index.as_query_engine()

# Perform queries
response_1 = query_engine.query("What is global warming?")
print(response_1)

response_2 = query_engine.query("How can we reduce our carbon footprint?")
print(response_2)
```

## Notes

* You can specify a namespace when creating the `UpstashVectorStore` instance:
  ```python
  vector_store = UpstashVectorStore(
      url="your_upstash_url",
      token="your_upstash_token",
      namespace="your_namespace"
  )
  ```

* Visit the [LlamaIndex documentation](https://docs.llamaindex.ai/en/latest) for more details.

# LlamaParse with Upstash Vector
Source: https://upstash.com/docs/vector/integrations/llamaparse

You can use LlamaParse with Upstash Vector to parse documents and perform semantic queries on the content. LlamaParse simplifies the extraction of structured information from files, which can then be indexed and queried using Upstash Vector.

## Install

```bash
pip install llama-index upstash-vector llama-index-vector-stores-upstash python-dotenv
```

## Setup

Create a Vector Index in the [Upstash Console](https://console.upstash.com). Set the index with:
* **Dimensions**: 1536
* **Distance Metric**: Cosine

Add the required environment variables to a `.env` file:

```
UPSTASH_VECTOR_REST_URL=your_upstash_url
UPSTASH_VECTOR_REST_TOKEN=your_upstash_token
LLAMA_CLOUD_API_KEY=your_llama_cloud_api_key
```

## Usage

### Parsing Documents

Use LlamaParse to parse a document. For example:

```python
from llama_parse import LlamaParse
from llama_index.core import SimpleDirectoryReader

# Initialize the parser
parser = LlamaParse(result_type="markdown")

# Parse a document
file_extractor = {".txt": parser}
documents = SimpleDirectoryReader(
    input_files=["./documents/global_warming.txt"],
    file_extractor=file_extractor
).load_data()
```

### Querying the Parsed Content

Once the document is parsed, you can index it using Upstash Vector and query its content:

```python
from llama_index.core import VectorStoreIndex
from llama_index.vector_stores.upstash import UpstashVectorStore
from llama_index.core import StorageContext
from dotenv import load_dotenv
import os

# Load environment variables
load_dotenv()

# Set up Upstash Vector Store
vector_store = UpstashVectorStore(
    url=os.getenv("UPSTASH_VECTOR_REST_URL"),
    token=os.getenv("UPSTASH_VECTOR_REST_TOKEN")
)

# Create storage context and index the parsed document
storage_context = StorageContext.from_defaults(vector_store=vector_store)
index = VectorStoreIndex.from_documents(documents, storage_context=storage_context)

# Perform a query
query_engine = index.as_query_engine()
response = query_engine.query("What is the main topic discussed in the document?")
```

To learn more, visit the [LlamaParse documentation](https://docs.cloud.llamaindex.ai/llamaparse/getting_started/get_an_api_key).

# Changelog
Source: https://upstash.com/docs/vector/overall/changelog

<Update label="August 2025">
* Introduced a new api to [rename a namespace](../api/endpoints/rename-namespace)
</Update>

<Update label="March 2025">
* Allow deleting vectors with [id prefix](../api/endpoints/delete#param-prefix)
  or [metadata filter](../api/endpoints/delete#param-filter).
* Allow [fetching](../api/endpoints/fetch#param-prefix)
  and [ranging](../api/endpoints/range#param-prefix) over vectors with id prefix.
</Update>

<Update label="February 2025">
* Introduced official SDK's for [PHP & Laravel](../sdks/php/getting-started).
</Update>

<Update label="January 2025">
* Introduced [Sparse and Hybrid indexes](https://upstash.com/blog/sparse-and-hybrid-indexes).
    * [Sparse Indexes](../features/sparseindexes) details.
    * [Hybrid Indexes](../features/hybridindexes) details.
</Update>

<Update label="September 2024">
* Introduced [resumable query/search](../features/resumablequery) functionality, allowing to initiate and continue queries across multiple api calls.
    * [Typescript SDK](../sdks/ts/commands/resumable-query)
    * [Python SDK](../sdks/py/example_calls/resumable-query)
* Added embedding latency charts to the Upstash Console vector usage page.
</Update>

<Update label="July 2024">
Added new [`HAS FIELD`](../features/filtering#has-field) and [`HAS NOT FIELD`](../features/filtering#has-not-field) metadata filtering operators.
</Update>

<Update label="June 2024">
* Implemented a new feature to store raw data in text format alongside metadata. See [Metadata and Data](../features/metadata#data).
* Added an API for updating vector, data, or metadata. It's also possible to update the metadata without overwriting all.
See [Update Vector](../api/endpoints/update) API.
* Added reset all namespaces API. See [Reset Namespace](../api/endpoints/reset) API.
* Improved query APIs to send a batch of queries in a single request. See [Query](../api/endpoints/query) API.
</Update>

<Update label="May 2024">
* Introduced [namespaces feature](/docs/vector/features/namespaces).
* Added GCP US-Central1 region.
</Update>

<Update label="April 2024">
Added option to upsert and query raw data using [Upstash embedding service](/docs/vector/features/embeddingmodels).
</Update>

<Update label="February 2024">
Implemented metadata filtering with SQL-like syntax. See [Metadata Filtering](/docs/vector/features/filtering).
</Update>

<Update label="January 2024">
[Initial release!](https://upstash.com/blog/introducing-vector-database)
</Update>

# Compare
Source: https://upstash.com/docs/vector/overall/compare

// todo melek

# Getting Started
Source: https://upstash.com/docs/vector/overall/getstarted

<Check >
**Prerequisite**

You need an Upstash account before creating a vector, create one
[here](https://console.upstash.com).

</Check>

## Create an Index

Once you logged in, you can create a Vector Index by clicking on the `Create Index` button in the Vector tab.

<img />

**Name:** Type a name for your index.

**Region:** Choose the region for your index. For optimal performance, select the region closest to your applications. We plan to support additional regions and cloud providers. Feel free to send your requests to [support@upstash.com](mailto:support@upstash.com)

**Type:** The type of index: Dense, [Sparse](/docs/vector/features/sparseindexes) or [Hybrid](/docs/vector/features/hybridindexes). For semantic search, you can prefer dense. For full text (or keyword) search, you can prefer sparse. If you need a combination, you can choose hybrid.

If you choose Dense or Hybrid as index type, you will also be presented with options to select the dimensions and distance metric of your index.

<Tip>
  For the purpose of using the code samples on this page, you can create a dense index with `dimension: 2`. Distance metric can be any of the options.
</Tip>

Once you pick these options, you will choose a plan:

**Free:** The free plan is suitable for small projects. It has a limit of 10,000 queries and 10,000 updates daily.

**Pay as You Go:** Pay as you go plan is a flexible plan with per-request-pricing. It is suitable for projects with unpredictable traffic.

**Fixed:** Fixed plan is suitable for projects with predictable traffic. It has a fixed monthly price with 1M query and 1M updates daily.

**Pro:** Pro plan is suitable for projects with high traffic and storage needs. It has a fixed monthly price with extra security and isolation features.

**Enterprise:** If you plan to have over a billion vectors then Enterprise plan is for you. It has a fixed monthly price with extra security and isolation features. Contact us at [sales@upstash.com](mailto:sales@upstash.com) for more information.

## Insert Index

You can access data in your index using REST API or our SDKs. You can copy the sample code from the `Connect` section in the console.

<Tabs>

<Tab title="Python">
```python
from upstash_vector import Index

index = Index(url="UPSTASH_VECTOR_REST_URL", token="UPSTASH_VECTOR_REST_TOKEN")

index.upsert(
  vectors=[
    ("1", [0.6, 0.8], {"field": "value"}),
  ]
)
```
</Tab>

<Tab title="JavaScript">
```ts
import { Index } from "@upstash/vector";

const index = new Index({
    url: "UPSTASH_VECTOR_REST_URL",
    token: "UPSTASH_VECTOR_REST_TOKEN",
})

await index.upsert({ id: "1", vector: [0.6, 0.8], metadata: {field: "value"} })
```
</Tab>

<Tab title="Go">
```go
import "github.com/upstash/vector-go"

func main() {
  index := vector.NewIndex("UPSTASH_VECTOR_REST_URL", "UPSTASH_VECTOR_REST_TOKEN")

index.Upsert(vector.Upsert{
	  Id:       "1",
	  Vector:   []float32{0.6, 0.8},
	  Metadata: map[string]any{"field": "value"},
  })
}
```
</Tab>

<Tab title="PHP">
```php
use Upstash\Vector\Index;
use Upstash\Vector\VectorUpsert;

$index = new Index(
  url: 'UPSTASH_VECTOR_REST_URL',
  token: 'UPSTASH_VECTOR_REST_TOKEN',
);

$index->upsert(new VectorUpsert(
  id: '1',
  vector: [0.6, 0.8],
  metadata: ['field' => 'value'],
));
```
</Tab>

<Tab title="curl">
```shell
curl $UPSTASH_VECTOR_REST_URL/upsert \
  -X POST \
  -H "Authorization: Bearer $UPSTASH_VECTOR_REST_TOKEN" \
  -d '{"id": "1", "vector": [0.6, 0.8], "metadata": {"field": "value"}}'
```
</Tab>

</Tabs>

## Query Index
You can perform a similarity search by providing a query vector as a parameter. The dimension of the query vector must match the dimension of your index. Also, you can query by metadata filtering.

<Note>
Upstash is eventually consistent, so there may be a delay before the newly inserted or updated vectors are ready for querying.
</Note>

<Tabs>

<Tab title="Python">
```python
from upstash_vector import Index

index = Index(url="UPSTASH_VECTOR_REST_URL", token="UPSTASH_VECTOR_REST_TOKEN")

index.query(
    vector=[0.6, 0.8],
    top_k=3,
    include_metadata=True,
)
```
</Tab>

<Tab title="JavaScript">
```ts
import { Index } from "@upstash/vector";

const index = new Index({
  url: "UPSTASH_VECTOR_REST_URL",
  token: "UPSTASH_VECTOR_REST_TOKEN",
})

await index.query({ vector: [0.6, 0.8], topK: 3, includeMetadata: true })
```
</Tab>

<Tab title="Go">
```go
import "github.com/upstash/vector-go"

func main() {
  index := vector.NewIndex("UPSTASH_VECTOR_REST_URL", "UPSTASH_VECTOR_REST_TOKEN")

index.Query(vector.Query{
	  Vector:          []float32{0.6, 0.8},
	  TopK:            3,
	  IncludeMetadata: true,
  })
}
```
</Tab>

<Tab title="PHP">
```php
use Upstash\Vector\Index;
use Upstash\Vector\VectorQuery;

$index = new Index(
  url: '<UPSTASH_VECTOR_REST_URL>',
  token: '<UPSTASH_VECTOR_REST_TOKEN>',
);

$index->query(new VectorQuery(
  vector: [0.6, 0.8],
  topK: 3,
  includeMetadata: true,
));
```
</Tab>

<Tab title="curl">
```shell
curl $UPSTASH_VECTOR_REST_URL/query \
  -H "Authorization: Bearer $UPSTASH_VECTOR_REST_TOKEN" \
  -d '{"vector": [0.6, 0.8], "topK": 3, "includeMetadata": "true"}'
```
</Tab>

</Tabs>

## Usage and Data Browser

In Upstash console, you can see the charts of your index:

<img />

There are following charts:

* **Daily Requests:** The number of queries and updates to your index in the last 5 days.
* **Throughput:** The number of queries and updates to your index in the selected time period.
* **Latency:** The mean and P99 latency of queries and updates to your index in the selected time period.
* **Vector Count:** The number of vectors in your index in the selected time period.
* **Data Size:** The size of your index in the selected time period.

You can also query your index with a simple UI:

<img />

# llms.txt
Source: https://upstash.com/docs/vector/overall/llms-txt

# Pricing & Limits
Source: https://upstash.com/docs/vector/overall/pricing

Please check our [pricing page](https://upstash.com/pricing/vector) for the most up-to-date information on pricing and limits.

# What is Upstash Vector?
Source: https://upstash.com/docs/vector/overall/whatisvector

Upstash Vector is a **serverless vector database designed for high-performance vector search at scale**. It powers advanced systems in areas such as:

* Natural Language Processing (NLP)
* Retrieval Augmented Generation (RAG)
* Recommendation engines
* Image recognition
* Clustering or classification

... without any infrastructure management.

***

## What is a Vector Database?

Vector databases are specifically designed to store and efficiently search high-dimensional vectors. These vectors can represent images, sounds, text, or other media for powerful similarity search across content that traditional databases struggle to represent properly.

Their specialization makes vector stores the perfect foundation for similarity-based search. Using specialized approximation algorithms such as Approximate Nearest Neighbor (ANN), they can typically provide much higher indexing and query performance than general-purpose databases or extensions like pgvector.

***

## Upstash Vector Core Features:

* **High-Performance Queries:** Upstash Vector is powered by DiskANN[1], a highly efficient approximation algorithm that delivers very high recall rates (resulting in better output quality) and ultra-low latency. See [ANN Search Algorithm](../features/algorithm) for more insight into the technology behind our vector database.

* **Batteries Included:** A convenient REST API and SDKs with first-class Python and TypeScript support.

* **Serverless Pricing:** Upstash Vector is fully managed and serverless, we take care of the hosting and high availability complexities. You only pay for what you actually use. See our [Vector Pricing Page](https://upstash.com/pricing/vector) for more details.

* **Multiple Similarity Functions:** We natively support similarity functions such as Euclidean distance, cosine similarity, and dot product.
  See [Vector Similarity](../features/similarityfunctions) for more details.

* **Metadata Support:** Attach metadata to vectors to store additional information or context. When querying an index, you can then include a metadata filter to limit the search to records that match a filter expression. See [Metadata Documentation](../features/metadata) for more details.

***

### References

1. Subramanya, S. J., Devvrit, Kadekodi, R., Krishaswamy, R., Simhadri, H. V. (2019). _DiskANN: Fast Accurate Billion-Point Nearest Neighbor Search on a Single Node_. In Proceedings of the 33rd International Conference on Neural Information Processing Systems (NeurIPS '19), Article No.: 1233, Pages 13766–13776. [https://dl.acm.org/doi/abs/10.5555/3454287.3455520]

# Go SDK
Source: https://upstash.com/docs/vector/sdk/gosdk

# Semantic Cache JS
Source: https://upstash.com/docs/vector/sdk/semantic-cache-js

# Semantic Cache Python
Source: https://upstash.com/docs/vector/sdk/semantic-cache-py

- [Deleting Vectors](https://upstash.com/docs/vector/sdks/php/commands/delete-vectors.md)
- [Fetching Vectors](https://upstash.com/docs/vector/sdks/php/commands/fetch.md)
- [Info](https://upstash.com/docs/vector/sdks/php/commands/info.md)
- [Querying Vectors](https://upstash.com/docs/vector/sdks/php/commands/query.md)
- [Reset](https://upstash.com/docs/vector/sdks/php/commands/reset.md)
- [Upserting Data with Embedding Models](https://upstash.com/docs/vector/sdks/php/commands/upsert-data.md)
- [Upserting Vectors](https://upstash.com/docs/vector/sdks/php/commands/upsert-vectors.md)

# Getting Started
Source: https://upstash.com/docs/vector/sdks/php/getting-started

`upstash/vector` is a PHP SDK for Upstash Vector, enabling easier operations on Vector Store.

Using `upstash/vector` you can:

* Upsert a vector with metadata to an index.
* Fetching the vectors with specified IDs.
* Querying a vector over pre-defined embeddings.
* Remove vectors from an index.
* Access index stats.
* Reset everything related to an index.

You can find the Github Repository [here](https://github.com/upstash/vector-php).

## Install

To install the SDK, you can use composer:

```shell composer
composer require upstash/vector
```

<Note>
We also built a Laravel package that you can use to integrate the SDK with your Laravel application.
[Learn more about our Laravel SDK](./laravel)
</Note>

## Usage

### Initializing the client

There are two pieces of configuration required to use the Upstash vector client: a REST token and REST URL. These values can be passed using environment variables or in code through the initialization of the Index. Find your configuration values in the console dashboard at [https://console.upstash.com/](https://console.upstash.com/).

#### Using environment variables

The environment variables used to configure the client are the following. You can follow [this guide](/docs/vector/overall/getstarted) to retrieve credentials.

```bash
UPSTASH_VECTOR_REST_URL="your_rest_url"
UPSTASH_VECTOR_REST_TOKEN="your_rest_token"
```

When these environment variables are set, you can initialize the client from the environment.

```php
use Upstash\Vector\Index;

$index = Index::fromEnv();
```

#### Manual Initialization

If you prefer to pass these values in code, the constructor accepts as parameters the `url` and `token` values. This
could be useful if your application needs to interact with multiple projects, each with a different configuration.

```php
use Upstash\Vector\Index;

$index = new Index(
  url: "<UPSTASH_VECTOR_REST_URL>",
  token: "<UPSTASH_VECTOR_REST_TOKEN>",
);
```

# Getting Started with Laravel
Source: https://upstash.com/docs/vector/sdks/php/laravel

`upstash/vector-laravel` is a dedicated Laravel SDK for Upstash Vector, that is built on top of our official PHP SDK.

By using `upstash/vector-laravel` you will be able to:

* Integrate Upstash Vector by only installing the package and setting environment variables.
* A native Vector facade to interact with your vector database.
* Able to maintain multiple index connections in your application.

You can find the Github Repository [here](https://github.com/upstash/vector-laravel).

## Install

To install the SDK, you can use composer:

```shell composer
composer require upstash/vector-laravel
```

## Setup

```bash
UPSTASH_VECTOR_REST_URL="your_rest_url"
UPSTASH_VECTOR_REST_TOKEN="your_rest_token"
```

## Usage

Our Laravel SDK will configure your index into the Laravel Service Container. You can access it by calling the `Vector` facade
or by injecting the `IndexInterface` into your controllers.

### Vector Facade

When these environment variables are set, you can start using your Index by calling the `Vector` facade.

```php
use Upstash\Vector\Laravel\Facades\Vector;

Vector::getInfo(); // Fetches the index info.
```

### Dependency Injection

If you prefer to avoid using the facade, you can inject the `IndexInterface` into your controllers.

```php
namespace App\Http\Controllers;

use Upstash\Vector\Contracts\IndexInterface;

class Controller
{
    public function index(IndexInterface $index)
    {
        $namespaces = $index->listNamespaces();

return response()->json(['namespaces' => $namespaces]);
    }
}
```

## Configuration

You can also configure the SDK to be able to use multiple indexes in your application.

For doing that you can publish the configuration file by running the following command:
```shell
php artisan vendor:publish --tag="vector-config"
```

You'll get a new file under `config/vector.php` that you can edit to add your indexes.

```php
return [
    'default' => env('UPSTASH_VECTOR_CONNECTION', 'default'),

'connections' => [
        'default' => [
            'url' => env('UPSTASH_VECTOR_REST_URL'),
            'token' => env('UPSTASH_VECTOR_REST_TOKEN'),
        ],
    ],
];
```

### Multiple Connections

If you want to use multiple connections in your application, you can add them to the `connections` array as shown below:

```php
return [
    'default' => env('UPSTASH_VECTOR_CONNECTION', 'default'),

'connections' => [
        'default' => [
            'url' => env('UPSTASH_VECTOR_REST_URL'),
            'token' => env('UPSTASH_VECTOR_REST_TOKEN'),
        ],
        'another' => [
            'url' => env('SECOND_UPSTASH_VECTOR_REST_URL'),
            'token' => env('SECOND_UPSTASH_VECTOR_REST_TOKEN'),
        ],
    ],
];
```

To access a specific connection, you can use the `connection` method:

```php
use Upstash\Vector\Laravel\Facades\Vector;

Vector::connection('another')->getInfo();
```

# Delete
Source: https://upstash.com/docs/vector/sdks/py/example_calls/delete

## Method

The `delete` method allows you to remove vectors from the index based on their identifiers.
The command accepts the following parameters:

* `ids`: A list of identifiers of vectors to be deleted.
* `prefix`: A string prefix to match vector IDs. All vectors with IDs that start with this prefix will be deleted.
* `filter`: A metadata filter to match vectors to be deleted.

<Note>Only one of `ids`, `prefix`, or `filter` can be provided.</Note>

It returns the following field in response:

* `deleted`: An integer indicating how many vectors were deleted with the command.

## Delete Example

```python
from upstash_vector import Index

index = Index.from_env()

# Specify the identifiers of vectors to be deleted
ids_to_delete = ["id1", "id2", "id3"]

# Delete the specified vectors
delete_result = index.delete(ids=ids_to_delete)

# Display the number of vectors deleted
print("Number of Vectors Deleted:", delete_result.deleted)
```

Alternatively, you can delete a singular vector:

```python
index.delete("id-4")
```

Also, you can specify a namespace to operate on. When no namespace
is provided, the default namespace will be used.

```python
index.delete("id-4", namespace="ns")
```

## Delete with metadata filter

This will delete all vectors with metadata that matches the provided filter. For more information, see [Metadata Filtering](/docs/vector/features/filtering).

```python
index.delete(filter="age > 30")
```

## Delete with id prefix

This will delete all vectors with IDs that start with the prefix.

```python
index.delete(prefix="id-")
```

# Fetch
Source: https://upstash.com/docs/vector/sdks/py/example_calls/fetch

## Method

The `fetch` method allows you to retrieve vectors from the index based on their identifiers. It takes the following input parameters:

* `ids`: A string or a list of strings representing the identifiers of the vectors to be fetched.
* `prefix`: A string prefix to match vector IDs. All vectors with IDs that start with this prefix will be retrieved.
* `include_vectors`: A boolean flag indicating whether to include vectors in the fetch results.
* `include_metadata`: A boolean flag indicating whether to include metadata in the fetch results.
* `include_data`: A boolean flag indicating whether to include data in the fetch results.
* `namespace`: The namespace to use. When not specified, the default namespace is used.

As a response, following field is returned:

* `vectors`: A list containing information for each fetched vector, including `id`, `vector`, `sparse_vector`, `metadata`, and `data`.

## Fetch Example

```python
from upstash_vector import Index

index = Index.from_env()

# Specify the identifiers of vectors to be fetched
ids_to_fetch = ["id-1", "id-2", "id-3"]

# Fetch the specified vectors with vectors and metadata included
fetch_result = index.fetch(
    ids=ids_to_fetch,
    include_vectors=True,
    include_metadata=True,
    include_data=True,
)

# Display the fetched vectors
for vector_info in fetch_result:
    print("ID:", vector_info.id)
    print("Vector:", vector_info.vector)
    print("Metadata:", vector_info.metadata)
    print("Data:", vector_info.data)
```

Alternatively, you can fetch a singular vector:

```python
index.fetch("id-4")
```

Also, you can specify a namespace to operate on. When no namespace
is provided, the default namespace will be used.

```python
index.fetch("id-4", namespace="ns")
```

## Fetch with id prefix

This will fetch all vectors with IDs that start with the prefix.

<Warning>
  For fetching larger datasets with id prefix, prefer using the paginated
  `range` command to prevent timeouts.
</Warning>

```python
index.fetch(prefix="id-")
```

# Info
Source: https://upstash.com/docs/vector/sdks/py/example_calls/info

## Method

The `info` method provides statistical information about the index, returning the following fields:

* `vector_count`: The total number of vectors in the index.
* `pending_vector_count`: The number of vectors that are currently pending (not yet fully processed).
* `index_size`: The size of the index in bytes.
* `dimension`: How many dimensions the index has
* `similarity_function`: Similarity function chosen for the index
* `namespaces`: Map of namespace names of the index to their statistics.

## Info Example

```python
from upstash_vector import Index

index = Index.from_env()

from upstash_vector import Index

index = Index.from_env()

# Get statistical information about the index
info_result = index.info()

# Display the info result
print("Vector Count:", info_result.vector_count)
print("Pending Vector Count:", info_result.pending_vector_count)
print("Index Size:", info_result.index_size)
print("Dimension:", info_result.dimension)
print("Similarity Function:", info_result.similarity_function)

for ns, ns_info in info_result.namespaces.items():
    print("Namespace:", ns, "Vector Count:", ns_info.vector_count)
    print("Namespace:", ns, "Pending Vector Count:", ns_info.pending_vector_count)
```

# Query
Source: https://upstash.com/docs/vector/sdks/py/example_calls/query

## Method

To retrieve vectors from the index based on specific criteria, you can use the `query` method, which accepts the following parameters:

* `vector`: The reference vector for similarity comparison.
* `sparse_vector`: The sparse vector value to query.
* `data`: A string for text-based queries (mutually exclusive with vector).
* `include_metadata`: A boolean flag indicating whether to include metadata in the query results.
* `include_vector`: A boolean flag indicating whether to include vectors in the query results.
* `include_data`: A boolean flag indicating whether to include data in the query results.
* `top_k`: The number of top matching vectors to retrieve.
* `filter`: Metadata filtering of the vector is used to query your data based on the filters and narrow down the query results.
* `namespace`: The namespace to use. When not specified, the default namespace is used.
* `weighting_strategy`: Weighting strategy to be used for sparse vectors.
* `fusion_algorithm`: Fusion algorithm to use while fusing scores from hybrid vectors.
* `query_mode`: Query mode for hybrid indexes with Upstash-hosted embedding models.

As response, the object has the following fields:

* `id`: The identifier associated with the matching vector.
* `metadata`: Additional information or attributes linked to the matching vector.
* `score`: A measure of similarity indicating how closely the vector matches the query vector. The score is normalized to the range [0, 1], where 1 indicates a perfect match.
* `vector`: The vector itself (included only if `include_vector` is set to `True`).
* `sparse_vector`: The sparse vector itself (included only if `include_vector` is set to `True`).
* `data`: Additional unstructured information linked to the matching vector.

<Tip>If you wanna learn more about filtering check: [Metadata Filtering](/docs/vector/features/filtering)</Tip>

## Query Example

```python
import random

from upstash_vector import Index

index = Index.from_env()

# Generate a random vector for similarity comparison
dimension = 128  # Adjust based on your index's dimension
query_vector = [random.random() for _ in range(dimension)]

# Execute the query
query_result = index.query(
    vector=query_vector,
    include_metadata=True,
    include_data=True,
    include_vectors=False,
    top_k=5,
    filter="genre = 'fantasy' and title = 'Lord of the Rings'",
)

# Print the query result
for result in query_result:
    print("Score:", result.score)
    print("ID:", result.id)
    print("Vector:", result.vector)
    print("Metadata:", result.metadata)
    print("Data:", result.data)
```

## Batch Query Method

It is also possible to perform a batch of queries in a single
call to eliminate round trips to server.

## Batch Query Example

```python
import random

from upstash_vector import Index

index = Index.from_env()

# Generate a random vector for similarity comparison
dimension = 128  # Adjust based on your index's dimension
query_vectors = [[random.random() for _ in range(dimension)] for _ in range(2)]

# Execute the query
query_results = index.query_many(
    queries=[
        {
            "vector": query_vectors[0],
            "include_metadata": True,
            "include_data": True,
            "include_vectors": False,
            "top_k": 5,
            "filter": "genre = 'fantasy' and title = 'Lord of the Rings'",
        },
        {
            "vector": query_vectors[1],
            "include_metadata": False,
            "include_data": False,
            "include_vectors": True,
            "top_k": 3,
            "filter": "genre = 'drama'",
        },
    ]
)

for i, query_result in enumerate(query_results):
    print(f"Query-{i} result:")

# Print the query result
    for result in query_result:
        print("Score:", result.score)
        print("ID:", result.id)
        print("Vector:", result.vector)
        print("Metadata:", result.metadata)
        print("Data:", result.data)
```

Also, you can specify a namespace to operate on. When no namespace
is provided, the default namespace will be used.

```python
index.query(..., namespace="ns")
```

# Range
Source: https://upstash.com/docs/vector/sdks/py/example_calls/range

## Method

The `range` method allows you to retrieve vectors from the index within a specified range. The function accepts the following parameters:

* `cursor`: A cursor to start the range query.
* `prefix`: A string prefix to match vector IDs. All vectors with IDs that start with this prefix will be retrieved.
* `limit`: The maximum number of vectors to retrieve in a single query.
* `include_vectors`: A boolean flag indicating whether to include vectors in the range results.
* `include_metadata`: A boolean flag indicating whether to include metadata in the range results.
* `include_data`: A boolean flag indicating whether to include data in the range results.

As response, the object has the following fields:

* `next_cursor`: A cursor indicating the position to start the next range query. If `""`, there are no more results.
* `vectors`: A list containing information for each vector, including `id`, `vector`, and `metadata`.

<Note>
  The range command is stateless, meaning you need to pass all of the parameters
  in each subsequent request.
</Note>

## Range Example

```python
from upstash_vector import Index

index = Index.from_env()

# Execute the range query
range_result = index.range(
    cursor="",
    limit=10,
    include_vectors=False,
    include_metadata=True,
    include_data=True,
)

# Print the range result
print("Next Cursor:", range_result.next_cursor)

for vector_info in range_result.vectors:
    print("ID:", vector_info.id)
    print("Vector:", vector_info.vector)
    print("Metadata:", vector_info.metadata)
    print("Data:", vector_info.data)
```

## Range with id prefix

This will retrieve all vectors with IDs that start with the prefix.

```python
index.range(prefix="id-")
```

## Scanning Whole Index

For scanning the entire index, you can use a similar loop as shown below:

```python
res = index.range(cursor="", limit=5)
print(res.vectors)

while res.next_cursor != "":
    res = index.range(cursor=res.next_cursor, limit=10)
    print(res.vectors)
```

Also, you can specify a namespace to operate on. When no namespace
is provided, the default namespace will be used.

```python
index.range(..., namespace="ns")
```

# Reset
Source: https://upstash.com/docs/vector/sdks/py/example_calls/reset

## Method

The `reset` method allows you to clear all vectors and metadata from a particular
namespace or all namespaces of an index.

## Reset Example

Resets the default namespace.

```python
from upstash_vector import Index
index = Index.from_env()

index.reset()
```

## Reset Namespace Example

Resets the given namespace.

```python
from upstash_vector import Index
index = Index.from_env()

index.reset(namespace="ns")
```

## Reset All Namespaces

Resets all the namespaces of an index.

```python
from upstash_vector import Index
index = Index.from_env()

index.reset(all=True)
```

# Resumable Query
Source: https://upstash.com/docs/vector/sdks/py/example_calls/resumable-query

Resumable queries let you start a nearest-neighbor search and continue fetching
additional results later without restarting the search. This is useful for
pagination or when you want to stream results incrementally instead of loading
the whole result set into memory.

Quick example (sync):

```python
from upstash_vector import Index

index = Index()

# start a resumable query (returns initial results and a handle)
results, handle = index.resumable_query(
    vector=[0.1, 0.2],
    top_k=2,
    include_metadata=True,
    include_vectors=True,
    namespace="example-namespace",
)

with handle:
    # `results` contains the first batch
    for r in results:
        print(r.id, r.metadata, getattr(r, "vector", None))

# fetch more results (fetch_next returns a list)
    more = handle.fetch_next(3)
    for r in more:
        print(r.id)

# when the context block exits the handle is stopped automatically
```

Parameters

* vector (List[float] | SupportsToList | None) — query vector (mutually exclusive with `data`).
* top_k (int, default 10) — how many top matches to return in the initial batch.
* include_vectors (bool, default False) — include full vector values on results.
* include_metadata (bool, default False) — include metadata on results.
* filter (str, default "") — filter expression to narrow results by metadata.
* data (str | None) — text query for indexes using Upstash-hosted embedding models.
* namespace (str, default DEFAULT_NAMESPACE) — namespace to search in.
* include_data (bool, default False) — include stored `data` field (used for embedding indexes).
* max_idle (int, default 3600) — how long the server keeps the resumable query alive (seconds).
* sparse_vector (SparseVector | TupleAsSparseVectorT | None) — sparse vector for sparse/hybrid indexes.
* weighting_strategy (WeightingStrategy | None) — weighting strategy for sparse vectors.
* fusion_algorithm (FusionAlgorithm | None) — fusion algorithm for hybrid scoring.
* query_mode (QueryMode | None) — query mode for hybrid embedding indexes (e.g. SPARSE).

How it works

* The call to `resumable_query` returns a tuple `(result, handle)` where `result`
  is the first batch (list of QueryResult) and `handle` is a `ResumableQueryHandle`.
* Use `handle.fetch_next(n)` (or `await handle.fetch_next(n)`) to retrieve the next
  `n` results. If no more results are available an empty list is returned.
* Always stop the handle when finished (use `with handle:` / `async with handle:` or
  call `handle.stop()` / `await handle.stop()`). After the handle is stopped, further
  calls to `fetch_next` or `stop` raise an error (tests expect UpstashError).

Examples

Simple paging (sync)

```python
results, handle = index.resumable_query(vector=[0.1, 0.2], top_k=2, namespace="ns")

with handle:
    all_results = list(results)
    while True:
        next_batch = handle.fetch_next(2)
        if not next_batch:
            break
        all_results.extend(next_batch)

# handle is stopped after exiting the context manager
```

Sparse / hybrid example (showing advanced options)

```python
from upstash_vector.types import SparseVector, WeightingStrategy, FusionAlgorithm

scores, handle = index.resumable_query(
    vector=[0.1, 0.1],
    sparse_vector=([0], [0.1]),
    top_k=2,
    include_vectors=True,
    include_metadata=True,
    include_data=True,
    weighting_strategy=WeightingStrategy.IDF,
    fusion_algorithm=FusionAlgorithm.DBSF,
    namespace="hybrid-ns",
)

with handle:
    for s in scores:
        print(s.id, getattr(s, "vector", None), getattr(s, "sparse_vector", None))
    more = handle.fetch_next(1)
    print("more:", more)
```

Notes

* The server enforces a limit on the number of active resumable queries; keep them
  short-lived and call `stop()` when finished. The default `max_idle` is 3600 seconds.
* After calling `stop()` (explicitly or via context manager), further `fetch_next` or
  `stop` calls will raise an error.

# Update
Source: https://upstash.com/docs/vector/sdks/py/example_calls/update

## Methods

The `update` method enables you to update the `vector`, `metadata`, or `data`
of a vector.

## Update Example

```python
from upstash_vector import Index

index = Index.from_env()

updated = index.update(
    id="id1",
    metadata={"new": "metadata"},
    data="new-data",
)

print(updated)
```

## Patch Metadata Example

It is also possible to patch metadata (update or delete existing fields or
set new fields) according the [JSON Merge Patch](https://datatracker.ietf.org/doc/html/rfc7386) algorithm.

```python
from upstash_vector import Index
from upstash_vector.types import MetadataUpdateMode

index = Index.from_env()

updated = index.update(
    id="id2",
    metadata={
        "existing-field": "new-value",
        "existing-field-to-delete": None,
        "new-field": "new-value",
    },
    metadata_update_mode=MetadataUpdateMode.PATCH,
)

print(updated)
```

Also, you can specify a namespace to operate on. When no namespace
is provided, the default namespace will be used.

```python
index.update(..., namespace="ns")
```

# Upsert
Source: https://upstash.com/docs/vector/sdks/py/example_calls/upsert

## Methods
The `upsert` method enables you to insert or update vectors in the index.
You can perform upsert operations in three ways: using a vector object, a tuple, or a dictionary.

### Upsert Via Vector Object

```python
import random

from upstash_vector import Index, Vector

index = Index.from_env()

dimension = 128  # Adjust based on your index's dimension
upsert_amount = 100

vectors = [
    Vector(
        id=f"generated-id-{i}",
        vector=[random.random() for _ in range(dimension)],
        metadata={"some_field": f"some_value-{i}"},
        data=f"some-unstructured-data-{i}",
    )
    for i in range(upsert_amount)
]

index.upsert(vectors=vectors)
```

### Upsert Via Tuple

```python
import random

from upstash_vector import Index

index = Index.from_env()

dimension = 128  # Adjust based on your index's dimension
upsert_amount = 100

vectors = [
    (
        f"generated-id-{i}",
        [random.random() for _ in range(dimension)],
        {"some_field": f"some_value-{i}"},
        f"some-unstructured-data-{i}",
    )
    for i in range(upsert_amount)
]

index.upsert(vectors=vectors)
```

### Upsert Via Dictionary

```python
import random

from upstash_vector import Index

index = Index.from_env()

dimension = 128  # Adjust based on your index's dimension
upsert_amount = 100

vectors = [
    {
        "id": f"generated-id-{i}",
        "vector": [random.random() for _ in range(dimension)],
        "metadata": {"some_field": f"some_value-{i}"},
        "data": f"some-unstructured-data-{i}",
    }
    for i in range(upsert_amount)
]

index.upsert(vectors=vectors)
```

Also, you can specify a namespace to operate on. When no namespace
is provided, the default namespace will be used.

```python
index.upsert(..., namespace="ns")
```

# Features
Source: https://upstash.com/docs/vector/sdks/py/features

# Retry Mechanism

The `upstash-vector` SDK incorporates a reliable retry mechanism to manage network or API issues.
In the event of a failed request, the SDK automatically attempts up to three retries,
with each attempt spaced one second apart.

For customization of the retry behavior, you have the flexibility to set the `retries` and
`retry_interval` (in seconds) parameters according to your specific requirements.
For instance:

```python
from upstash_vector import Index

# Try 5 times with a 2-second interval between retries
index = Index.from_env(retries=5, retry_interval=2.0)
```

# Telemetry

This library sends anonymous telemetry data to help us improve your experience.
We collect the following:

* SDK version
* Platform (Vercel, AWS)
* Python Runtime version

You can opt out by passing `allow_telemetry=False` when initializing the Redis client:

```py
idx = Index("INDEX_URL", "INDEX_TOKEN", allow_telemetry=False)
```

# Getting Started
Source: https://upstash.com/docs/vector/sdks/py/gettingstarted

The `upstash-vector` SDK is a lightweight, HTTP-based Upstash Vector client designed for Python. It seamlessly operates in both serverless and serverful environments, ensuring optimal compatibility across various connection setups.

This SDK simplifies interaction with Upstash Vector through the [Upstash Vector API](https://docs.upstash.com/vector/api/get-started).

It is designed to work with Python versions 3.8 and above.

Explore the source code, contribute, and stay informed through our [GitHub Repository](https://github.com/upstash/vector-py).

## Install

To begin using `upstash-vector`, you can install it via PyPI using the following command:

```bash
pip install upstash-vector
```

## Usage

Before using upstash-vector, you'll need to set up a vector database on [Upstash](https://console.upstash.com/). Once created, grab your URL and TOKEN from the Upstash console.

To initialize the index client:

```python
from upstash_vector import Index
index = Index(url="UPSTASH_VECTOR_REST_URL", token="UPSTASH_VECTOR_REST_TOKEN")
```

Alternatively, you can automatically load the credentials from the environment:

```python
from upstash_vector import Index
index = Index.from_env()
```

For serverless environments that allow it, it's recommended to initialize the client outside the request handler to be reused while your function is still "hot."

Here's an example of how you can use the SDK in your Python application:

```python
import random
from upstash_vector import Index

# Initialize the index client using environment variables
index = Index.from_env()

def main():
    # Define the dimension based on the index configuration
    dimension = 128
    # Generate a random vector for upsert
    vector_to_upsert = [random.random() for _ in range(dimension)]
    # Additional metadata associated with the vector
    metadata = {"text": "example test for metadata"}

# Upsert the vector into the index
    index.upsert(vectors=[
        ("id-for-vector", vector_to_upsert, metadata)
    ])

```
The example above demonstrates how to upsert a vector with metadata using the SDK into the Upstash Vector database.

## More SDK Features
For additional functionalities and usage examples, check out the [Commands](/docs/vector/sdks/py/example_calls) section in the documentation.

# Advanced
Source: https://upstash.com/docs/vector/sdks/ts/advanced

## Request Timeout

You can configure the SDK so that it will throw an error if the request takes longer than a specified time.

You can achieve this using the signal parameter like this:

```ts

const index = new Index({
  url: "<UPSTASH_VECTOR_REST_URL>",
  token: "<UPSTASH_VECTOR_REST_TOKEN>",
  // set a timeout of 1 second
  signal: () => AbortSignal.timeout(1000),
});

try {
  await index.query({ ... })
} catch (error) {
  if (error.name === "TimeoutError") {
    console.error("Request timed out");
  } else {
    console.error("An error occurred:", error);
  }
}
```

## Telemetry

This sdk sends anonymous telemetry data to help us improve your experience.
We collect the following:

* SDK version
* Platform (Cloudflare, AWS or Vercel)
* Runtime version (node@18.x)

You can opt out by setting the `UPSTASH_DISABLE_TELEMETRY` environment variable
to any truthy value.

```sh
UPSTASH_DISABLE_TELEMETRY=1
```

- [Delete](https://upstash.com/docs/vector/sdks/ts/commands/delete.md)
- [Fetch](https://upstash.com/docs/vector/sdks/ts/commands/fetch.md)
- [Info](https://upstash.com/docs/vector/sdks/ts/commands/info.md)
- [Query](https://upstash.com/docs/vector/sdks/ts/commands/query.md)
- [Range](https://upstash.com/docs/vector/sdks/ts/commands/range.md)
- [Reset](https://upstash.com/docs/vector/sdks/ts/commands/reset.md)
- [Resumable Query](https://upstash.com/docs/vector/sdks/ts/commands/resumable-query.md)
- [Upsert](https://upstash.com/docs/vector/sdks/ts/commands/upsert.md)

# Contributing
Source: https://upstash.com/docs/vector/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 vector database on [Upstash](https://console.upstash.com/).

## Code Formatting

```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/vector/sdks/ts/getting-started

`@upstash/vector` is a Typescript SDK for Upstash Vector, enabling easier operations on Vector Store with full type coverage.

Using `@upstash/vector` you can:

* Upsert a vector with metadata to an index.
* Fetching the vectors with specified IDs.
* Querying a vector over pre-defined embeddings.
* Delete vectors from an index.
* Access index stats.
* Reset everything related to an index.

You can find the Github Repository [here](https://github.com/upstash/vector-js).

## Install

<CodeGroup>
```shell npm
npm install @upstash/vector
```

```shell pnpm
pnpm add @upstash/vector
```

</CodeGroup>

## Usage

### Initializing the client

There are two pieces of configuration required to use the Upstash vector 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 at [https://console.upstash.com/](https://console.upstash.com/).

#### Using environment variables

The environment variables used to configure the client are the following. You can follow [this guide](/docs/vector/overall/getstarted) to retrieve credentials.

```bash
UPSTASH_VECTOR_REST_URL="your_rest_url"
UPSTASH_VECTOR_REST_TOKEN="your_rest_token"
```

When these environment variables are set, the client constructor does not require any additional arguments.

```typescript
import { Index } from "@upstash/vector";

const index = new Index();
```

#### Using a configuration object

```typescript
import { Index } from "@upstash/vector";

const index = new Index({
  url: "<UPSTASH_VECTOR_REST_URL>",
  token: "<UPSTASH_VECTOR_REST_TOKEN>",
});
```

## TypeScript Usage

### Index level types
The Vector SDK supports defining your metadata type at the index level for complete type-safety.

```typescript
import { Index } from "@upstash/vector";

type Metadata = { genre: string, year: number };

const index = new Index<Metadata>();
```

Passing a metadata type at the index level will provide strong type safety for the metadata coming back from or required for the following commands:
* `query`
* `upsert`
* `fetch`
* `range`

### Command level types

In some cases, you might not want to define a metadata type at the index level. In this case, you can either override the index level type definition for a specific command, or pass a metadata type to specific commands instead.

```typescript
import { Index } from "@upstash/vector";

type Metadata = { genre: string, year: number };

const index = new Index();

index.upsert<Metadata>({ id: 1, vector: [...], metadata: {
  genre: "comedy",
  year: 1990
}});
```

The passing of a strong metadata type is possible for each of the four index operations listed above, we use upsert as an example.

# Create and Deploy RAG Applications with Gradio
Source: https://upstash.com/docs/vector/tutorials/gradio-application

In this tutorial, we'll demonstrate how to use Gradio to build an interactive Semantic Search and Question Answering app using Hugging Face embeddings, Upstash Vector, and LangChain. Users can enter a question, and the app will retrieve relevant information and provide an answer.

### Important Note on Python Version

Recent Python versions may cause compatibility issues with `torch`, a dependency for Hugging Face models. Therefore, we recommend using **Python 3.9** to avoid any installation issues.

### Installation and Setup

First, we need to set up our environment and install the necessary libraries. Install the dependencies by running the following command:

```bash
pip install gradio langchain sentence_transformers upstash-vector python-dotenv transformers langchain-community langchain-huggingface
```

Next, create a `.env` file in your project directory with the following content, replacing `your_upstash_url` and `your_upstash_token` with your actual Upstash credentials:

```
UPSTASH_VECTOR_REST_URL=your_upstash_url
UPSTASH_VECTOR_REST_TOKEN=your_upstash_token
```

This configuration file will allow us to load the required environment variables.

### Code

We will load our environment variables, initialize the Hugging Face embeddings model, set up Upstash Vector, and configure a Hugging Face Question Answering model.

```python
# Import libraries
import gradio as gr
from dotenv import load_dotenv
from langchain_huggingface.embeddings import HuggingFaceEmbeddings
from langchain_community.vectorstores.upstash import UpstashVectorStore
from transformers import pipeline
from langchain.schema import Document

# Load environment variables
load_dotenv()

# Set up embeddings and Upstash Vector store
embeddings = HuggingFaceEmbeddings(model_name="sentence-transformers/all-mpnet-base-v2")
vector_store = UpstashVectorStore(embedding=embeddings)
```

Next, we will create sample documents, embed them using Hugging Face embeddings, and store them in Upstash Vector.

```python
# Sample documents to embed and store
documents = [
    Document(page_content="Global warming is causing sea levels to rise."),
    Document(page_content="AI is transforming many industries."),
    Document(page_content="Renewable energy is vital for sustainable development.")
]
vector_store.add_documents(documents=documents, batch_size=100, embedding_chunk_size=200)
```

When inserting documents, they are first embedded using the `Embeddings` object. Many embedding models, such as the Hugging Face models, support embedding multiple documents at once. This allows for efficient processing by batching documents and embedding them in parallel.

* The `embedding_chunk_size` parameter controls the number of documents processed in parallel when creating embeddings.

Once the embeddings are created, they are stored in Upstash Vector. To reduce the number of HTTP requests, the vectors are also batched when they are sent to Upstash Vector.

* The `batch_size` parameter controls the number of vectors included in each HTTP request when sending to Upstash Vector.

<Note type="info">
In the Upstash Vector free tier, there is a limit of 1000 vectors per batch.
</Note>

Now, we can set up a Question Answering model and the Gradio interface.

```python
# Set up a Hugging Face Question Answering model
qa_pipeline = pipeline("question-answering", model="distilbert-base-cased-distilled-squad")

# Gradio interface function
def answer_question(query):
    # Retrieve relevant documents from Upstash Vector
    results = vector_store.similarity_search(query, k=3)

# Use the most relevant document for QA
    if results:
        context = results[0].page_content
        qa_input = {"question": query, "context": context}
        answer = qa_pipeline(qa_input)["answer"]
        return f"Answer: {answer}\n\nContext: {context}"
    else:
        return "No relevant context found."

# Set up Gradio interface
iface = gr.Interface(
    fn=answer_question,
    inputs="text",
    outputs="text",
    title="RAG Application",
    description="Ask a question, and the app will retrieve relevant information and provide an answer."
)

# Launch the Gradio app
iface.launch()
```

### Running the App

After setting up the code, run your script to start the Gradio app. You will be presented with an interface where you can enter a question. The app will retrieve the most relevant information from the embedded documents and provide an answer based on the content.

### Notes

* **Deployment**: To create a public link, set `share=True` in `launch()`. This will generate a public URL for your Gradio app. This share link expires in 72 hours. For free permanent hosting and GPU upgrades, run `gradio deploy` from Terminal to deploy to [Hugging Face Spaces](https://huggingface.co/spaces)
* **Batch Processing**: The `batch_size` and `embedding_chunk_size` parameters allow you to control the efficiency of document processing and storage in Upstash Vector.
* **Namespaces**: Upstash Vector supports namespaces for organizing different types of documents. You can set a namespace while creating the `UpstashVectorStore` instance.

# Use Hugging Face Embeddings with Upstash Vector
Source: https://upstash.com/docs/vector/tutorials/huggingface-embeddings

In this tutorial, we'll demonstrate how to use Hugging Face embeddings with Upstash Vector and LangChain to perform a similarity search. We will upload a few sample documents, embed them using Hugging Face, and then perform a search query to find the most semantically similar documents.

### Important Note on Python Version

Recent Python versions may cause compatibility issues with `torch`, a dependency for Hugging Face models. Therefore, we recommend using **Python 3.9** to avoid any installation issues.

### Installation and Setup

First, we need to set up our environment and install the necessary libraries. Install the dependencies by running the following command:

```bash
pip install langchain sentence_transformers upstash-vector python-dotenv langchain-community langchain-huggingface
```

Next, create a `.env` file in your project directory with the following content, replacing `your_upstash_url` and `your_upstash_token` with your actual Upstash credentials:

```
UPSTASH_VECTOR_REST_URL=your_upstash_url
UPSTASH_VECTOR_REST_TOKEN=your_upstash_token
```

This configuration file will allow us to load the required environment variables.

### Code

We will load our environment variables and initialize the Hugging Face embeddings model along with the Upstash Vector store.

```python
# Load environment variables for API keys and Upstash configuration
from dotenv import load_dotenv
import os
load_dotenv()

# Import required libraries
from langchain_huggingface.embeddings import HuggingFaceEmbeddings
from langchain_community.vectorstores.upstash import UpstashVectorStore

# Initialize Hugging Face embeddings model
embeddings = HuggingFaceEmbeddings(model_name="sentence-transformers/all-mpnet-base-v2")

# Set up Upstash Vector Store (automatically uses the environment variables)
vector_store = UpstashVectorStore(embedding=embeddings)
```

Next, we will create sample documents and embed them using Hugging Face embeddings, then store them in Upstash Vector.

```python
# Import the required Document class from LangChain
from langchain.schema import Document

# Sample documents to embed and store as Document objects
documents = [
    Document(page_content="Global warming is causing sea levels to rise."),
    Document(page_content="Artificial intelligence is transforming many industries."),
    Document(page_content="Renewable energy is vital for sustainable development.")
]

# Embed documents and store in Upstash Vector with batching
vector_store.add_documents(
    documents=documents,
    batch_size=100,
    embedding_chunk_size=200
)

print("Documents with embeddings have been stored in Upstash Vector.")
```

* The `embedding_chunk_size` parameter controls the number of documents processed in parallel when creating embeddings.

Once the embeddings are created, they are stored in Upstash Vector. To reduce the number of HTTP requests, the vectors are also batched when they are sent to Upstash Vector.

* The `batch_size` parameter controls the number of vectors included in each HTTP request when sending to Upstash Vector.

<Note type="info">
In the Upstash Vector free tier, there is a limit of 1000 vectors per batch.
</Note>

Now, we can perform a semantic search.

```python
# Querying Vectors using a text query
query_text = "What are the effects of global warming?"
query_embedding = embeddings.embed_query(query_text)

# Perform similarity search with the query text
result_text_query = vector_store.similarity_search(
    query=query_text,
    k=5  # Number of top results to return
)

print("Results for text-based similarity search:")
for res in result_text_query:
    print(res.page_content)
```

Here's the output of our text-based similarity search:

```
Results for text-based similarity search:
Global warming is causing sea levels to rise.
Renewable energy is vital for sustainable development.
Artificial intelligence is transforming many industries.
```

Alternatively, you can perform a similarity search using the vector directly.

```python
# Querying Vectors using a vector directly
result_vector_query = vector_store.similarity_search_by_vector(
    embedding=query_embedding,
    k=5
)

print("Results for vector-based similarity search:")
for res in result_vector_query:
    print(res.page_content)
```

This will output similar results, as it is searching based on the similarity of the embedding.

### Notes

* You can specify batch sizes and chunk sizes to control the efficiency of document processing and storage in Upstash Vector.
* Upstash Vector supports namespaces for organizing different types of documents. You can set a namespace while creating the `UpstashVectorStore` instance.

To learn more about LangChain and its integration with Upstash Vector, visit the [LangChain documentation](https://python.langchain.com/docs/integrations/vectorstores/upstash/).

# Implement Semantic Search with LangChain
Source: https://upstash.com/docs/vector/tutorials/langchain

In this tutorial, we'll demonstrate how to use Upstash Vector with LangChain to perform a similarity search. We will upload a document about global warming and perform a search query to find the most semantically similar documents using embeddings generated automatically by Upstash.

### Installation and Setup

First, we need to create a Vector Index in the [Upstash Console](https://console.upstash.com). Once we have our index, we will copy the `UPSTASH_VECTOR_REST_URL` and `UPSTASH_VECTOR_REST_TOKEN` and paste them to our `.env` file. To learn more about index creation, you can check out [this page](https://docs.upstash.com/vector/overall/getstarted).

Add the following content to your `.env` file (replace with your actual URL and token):

```
UPSTASH_VECTOR_REST_URL=your_upstash_url
UPSTASH_VECTOR_REST_TOKEN=your_upstash_token
```

We now need to install the following libraries via PyPI:

```bash
pip install upstash-vector python-dotenv langchain langchain-community
```

### Code

We will load our environment variables and initialize the index from the environment variables (URL and token).

```python
from dotenv import load_dotenv
from langchain_community.vectorstores.upstash import UpstashVectorStore

load_dotenv()

# Create a vector store instance where embeddings are generated by Upstash
store = UpstashVectorStore(embedding=True)
```

Next, we will upload the `global_warming.txt` document to the Upstash Vector index.

```python
from langchain_community.document_loaders import TextLoader
from langchain_text_splitters import CharacterTextSplitter

# Load the document
loader = TextLoader("documents/global_warming.txt")
documents = loader.load()

# Split the document into chunks
text_splitter = CharacterTextSplitter(chunk_size=1000, chunk_overlap=0)
docs = text_splitter.split_documents(documents)
```

We will now insert the documents into the Upstash Vector index.

```python
inserted_vectors = store.add_documents(docs)
```

Finally, we will perform a semantic search.

```python
result = store.similarity_search("Technology's role in global warming.", k=5)
print(result)
```

Here's the output:
```
[Document(metadata={'source': 'documents/global_warming.txt'}, page_content='Technology and innovation play a crucial role in advancing sustainable food systems and mitigating the impact of global warming. Precision agriculture, for example, uses data analytics, remote sensing, and GPS technology to optimize the use of resources such as water, fertilizer, and pesticides. By applying inputs more efficiently, precision agriculture reduces waste, lowers GHG emissions, and improves crop yields.\n\nIn the realm of food production, alternative proteins—such as plant-based meats, lab-grown meats, and insect-based proteins—offer promising solutions to reduce the environmental impact of livestock farming. These innovations require fewer resources to produce and generate lower GHG emissions compared to traditional animal agriculture. Additionally, vertical farming and hydroponics allow for the cultivation of crops in controlled environments, using less land and water while reducing the need for chemical inputs.\n\nConclusion'),
 Document(metadata={'source': 'documents/global_warming.txt'}, page_content='Global warming presents a formidable challenge to food production systems, but sustainable food practices offer a viable solution to mitigate its effects. By adopting regenerative agriculture, reducing food waste, and shifting toward plant-based diets, humanity can reduce the environmental impact of agriculture while ensuring food security for future generations. Furthermore, technology and innovation will continue to play a pivotal role in advancing sustainable food systems, allowing for more efficient and eco-friendly food production methods. In the face of climate change, the integration of sustainable food practices is not only an environmental imperative but also a pathway toward a healthier and more resilient future for both people and the planet.'),
 Document(metadata={'source': 'documents/global_warming.txt'}, page_content='Global Warming and Sustainable Foods: An Inextricable Connection'),
 Document(metadata={'source': 'documents/global_warming.txt'}, page_content='One of the key components of sustainable food systems is regenerative agriculture, which focuses on restoring soil health, enhancing biodiversity, and sequestering carbon. Regenerative farming practices include crop rotation, cover cropping, agroforestry, and reduced tillage, all of which contribute to building healthy soils that can absorb and store carbon. By improving soil health, regenerative agriculture also increases the resilience of crops to climate change, as healthy soils retain more water and nutrients, making crops more resistant to droughts and pests.'),
 Document(metadata={'source': 'documents/global_warming.txt'}, page_content='Numerous studies have shown that shifting to plant-based diets can significantly reduce GHG emissions and mitigate the effects of global warming. According to a report by the United Nations Food and Agriculture Organization (FAO), reducing the consumption of animal-based foods could reduce global agricultural emissions by up to 50%. Moreover, plant-based diets are associated with reduced land and water use, as growing crops for direct human consumption is more resource-efficient than growing feed for livestock.\n\nIn addition to their environmental benefits, plant-based diets offer numerous health advantages. They are rich in fiber, vitamins, and minerals, and have been linked to lower risks of chronic diseases such as heart disease, diabetes, and certain cancers. As global populations grow and the demand for food increases, promoting plant-based diets offers a sustainable solution to addressing both environmental and nutritional challenges.\n\nThe Role of Technology and Innovation')]
```

### Notes

* You can also query with score using `similarity_search_with_score` method.

* Namespaces can be used to separate different types of documents. You can specify a namespace when creating the `UpstashVectorStore` instance.
```
store = UpstashVectorStore(embedding=True, namespace="my_namespace")
```

* You can use OpenAI's embeddings by setting `embedding=OpenAIEmbeddings()` in the `UpstashVectorStore` instance.
```
from langchain_openai import OpenAIEmbeddings
store = UpstashVectorStore(embedding=OpenAIEmbeddings())
```

To learn more about LangChain and its integration with Upstash Vector, you can visit the [LangChain documentation](https://python.langchain.com/docs/integrations/vectorstores/upstash/).

# RAG with LlamaIndex
Source: https://upstash.com/docs/vector/tutorials/llamaindex

In this tutorial, we’ll demonstrate how to use Upstash Vector with LlamaIndex to perform RAG (Retrieval-Augmented Generation). We will upload a document about global warming and generate responses to our questions based on the contents of the document.

### Installation and Setup

First, we need to create a Vector Index in the [Upstash Console](https://console.upstash.com). Make sure to set the index dimensions to 1536 and the distance metric to Cosine. Once we have our index, we will copy the `UPSTASH_VECTOR_REST_URL` and `UPSTASH_VECTOR_REST_TOKEN` and paste them into our `.env` file. To learn more about index creation, you can check out our [getting started page](https://docs.upstash.com/vector/overall/getstarted).

Add the following content to your `.env` file (replace with your actual URL, token and API key):

```
UPSTASH_VECTOR_REST_URL=your_upstash_url
UPSTASH_VECTOR_REST_TOKEN=your_upstash_token
OPENAI_API_KEY=your_openai_api_key
```

We now need to install the following libraries via PyPI:

```bash
pip install llama-index upstash-vector llama-index-vector-stores-upstash python-dotenv
```

### Code

We will load our environment variables, initialize the index, and configure it to use the specified dimensions and distance metric.

# Load environment variables
load_dotenv()
openai.api_key = os.environ["OPENAI_API_KEY"]

# Setup the Upstash vector store
upstash_vector_store = UpstashVectorStore(
    url=os.environ["UPSTASH_VECTOR_REST_URL"],
    token=os.environ["UPSTASH_VECTOR_REST_TOKEN"],
)

# Read the document about global warming from the documents directory
documents = SimpleDirectoryReader("./documents/").load_data()

# Initialize the storage context with the Upstash vector store
storage_context = StorageContext.from_defaults(vector_store=upstash_vector_store)

# Create the index from the loaded document with 1536 dimensions and cosine distance
index = VectorStoreIndex.from_documents(
    documents, storage_context=storage_context
)
```

Next, we will query the document:

```python
# Initialize the query engine
query_engine = index.as_query_engine()

# Query the document about global warming
res1 = query_engine.query("What is global warming?")
print(res1)

res2 = query_engine.query("How should we modify our diets to reduce our carbon footprint?")
print(res2)
```

### Sample Output

Here is the output of the queries:

```
Global warming refers to the long-term increase in Earth’s average temperature due to the accumulation of greenhouse gases (GHGs) such as carbon dioxide (CO2), methane (CH4), and nitrous oxide (N2O) in the atmosphere. The primary drivers of GHG emissions include the burning of fossil fuels for energy, industrial processes, deforestation, and unsustainable agricultural practices. As these gases trap heat, they create a “greenhouse effect,” leading to rising temperatures, melting polar ice caps, rising sea...

Shifting towards plant-based diets, which emphasize the consumption of vegetables, fruits, legumes, grains, and nuts, can significantly reduce our carbon footprint. Plant-based diets have a much lower environmental footprint compared to animal-based foods, particularly red meat, which is highly resource-intensive and contributes disproportionately to greenhouse gas emissions. Studies have shown that reducing the consumption of animal-based foods and increasing the intake of plant-based foods can help red...
```

### Notes

* Namespaces can be used to separate different types of documents. You can specify a namespace when creating the `UpstashVectorStore` instance:
```
vector_store = UpstashVectorStore(
    url=your_upstash_url,
    token=your_upstash_token,
    namespace=your_namespace,
    )
```

* To learn more about LlamaIndex and its integration with Upstash Vector, you can visit the [LlamaIndex documentation](https://docs.llamaindex.ai/en/latest).

# Parsing and Querying Documents with LlamaParse
Source: https://upstash.com/docs/vector/tutorials/llamaparse

In this tutorial, we’ll learn how to parse a document using LlamaParse and then query it using an LLM with Upstash Vector.

We’ll split this guide into two parts: parsing a document and then querying the parsed document.

## Installation and Setup

To get started, we need to set up our environment. You can install the necessary libraries using the following command in your terminal:

```bash
pip install llama-index upstash-vector llama-index-vector-stores-upstash python-dotenv
```

We also need to create a Vector Index in the [Upstash Console](https://console.upstash.com). Make sure to set the index dimensions to 1536 and the distance metric to Cosine. To learn more about index creation, you can check out our [getting started page](https://docs.upstash.com/vector/overall/getstarted).

Once we have our index, we will copy the `UPSTASH_VECTOR_REST_URL` and `UPSTASH_VECTOR_REST_TOKEN` and paste them into our `.env` file.

#### Environment Variables

Create a `.env` file in your project directory and add the following content:

```plaintext
UPSTASH_VECTOR_REST_URL=your_upstash_url
UPSTASH_VECTOR_REST_TOKEN=your_upstash_token
OPENAI_API_KEY=your_openai_api_key
LLAMA_CLOUD_API_KEY=your_llama_cloud_api_key
```

To get your `LLAMA_CLOUD_API_KEY`, you can follow the instructions in [the LlamaCloud documentation](https://docs.cloud.llamaindex.ai/llamaparse/getting_started/get_an_api_key).

## Part 1: Parsing a Document

We can now move on to parsing a document. In this example, we’ll parse a file named `global_warming.txt`.

```python
from llama_parse import LlamaParse
from llama_index.core import SimpleDirectoryReader

# Initialize the LlamaParse parser with the desired result format
parser = LlamaParse(result_type="markdown")  # "markdown" and "text" are available

# Parse the document using the parser
file_extractor = {".txt": parser}
documents = SimpleDirectoryReader(input_files=["./documents/global_warming.txt"], file_extractor=file_extractor).load_data()
```

<Note type="info">
    If you are using Jupyter Notebook, you need to allow nested event loops to parse the document.

You can do this by adding the following code snippet to your file:
```python
import nest_asyncio
nest_asyncio.apply()
```
</Note>

Now that we have our parsed data, we can query it.

## Part 2: Querying the Parsed Document with an LLM

In this part, we’ll use the `UpstashVectorStore` to create an index, and query the content. We’ll use OpenAI as the language model to interpret the data and respond to questions based on the document. You can use other LLMs that are supported by LlamaIndex as well.

```python
from llama_index.core import VectorStoreIndex
from llama_index.vector_stores.upstash import UpstashVectorStore
from llama_index.core import StorageContext
import openai

# Load environment variables for API keys and Upstash configuration
from dotenv import load_dotenv
import os
load_dotenv()

# Set up OpenAI API key
openai.api_key = os.getenv("OPENAI_API_KEY")

# Set up Upstash Vector Store
upstash_vector_store = UpstashVectorStore(
    url=os.getenv("UPSTASH_VECTOR_REST_URL"),
    token=os.getenv("UPSTASH_VECTOR_REST_TOKEN"),
)

# Create a storage context for Upstash Vector and index the parsed document
storage_context = StorageContext.from_defaults(vector_store=upstash_vector_store)
index = VectorStoreIndex.from_documents(documents, storage_context=storage_context)

# Create a query engine for the index and perform a query
query_engine = index.as_query_engine()
query = "What are the main points discussed in the document?"
response = query_engine.query(query)
print(response)
```

Here's the code output:

```plaintext
The main points discussed in the document include the impact of global warming on agriculture
and food production systems, the importance of adopting sustainable food practices to mitigate
these effects, the role of agriculture in contributing to global warming through GHG emissions,
deforestation, and the use of synthetic fertilizers, and the need for sustainable food systems
to address environmental challenges and ensure food security for future generations.
```

### Conclusion

With the ability to parse and query documents, you can efficiently summarize content, extract essential information, and answer questions based on the document’s details.

To learn more about LlamaIndex and its integration with Upstash Vector, you can visit the [LlamaIndex documentation](https://docs.llamaindex.ai/en/latest).

# Simple Semantic Search
Source: https://upstash.com/docs/vector/tutorials/semantic_search

In this tutorial, we'll demonstrate how to use Upstash Vector for semantic search. We will upload several documents and perform a search query to find the most semantically similar documents using embeddings generated automatically by Upstash.

### Installation and Setup

Add the following content to your `.env` file (replace with your actual URL and token):

```
UPSTASH_VECTOR_REST_URL=your_upstash_url
UPSTASH_VECTOR_REST_TOKEN=your_upstash_token
```

We now need to install the `upstash-vector` library via PyPI. Additionally, we will install `python-dotenv` to load environment variables from the `.env` file.

```bash
pip install upstash-vector python-dotenv
```

### Code

Create a Python script (e.g., `main.py`) and add the following code to perform semantic search using Upstash Vector:

```python main.py
from upstash_vector import Index
from dotenv import load_dotenv
import time

# Load environment variables from a .env file
load_dotenv()

# Initialize the index from environment variables (URL and token)
index = Index.from_env()

# Example documents to be indexed
documents = [
    {"id": "1", "text": "Python is a popular programming language."},
    {"id": "2", "text": "Machine learning enables computers to learn from data."},
    {"id": "3", "text": "Upstash provides low-latency database solutions."},
    {"id": "4", "text": "Semantic search is a technique for understanding the meaning of queries."},
    {"id": "5", "text": "Cloud computing allows for scalable and flexible resource management."}
]

# Reset the index to remove previous data
index.reset()

# Upsert documents into Upstash (embeddings are generated automatically)
for doc in documents:
    index.upsert(
        vectors=[
            (doc["id"], doc["text"], {"text": doc["text"]})
        ]
    )
    print(f"Document {doc['id']} inserted.")

# Wait for the documents to be indexed
time.sleep(1)

# Search for documents similar to the query
query = "What is Python?"
results = index.query(data=query, top_k=3, include_metadata=True)

# Display search results
print("Search Results:")
for result in results:
    print(f"ID: {result.id}")
    print(f"Score: {result.score:.4f}")
    print(f"Metadata: {result.metadata}")
    print("-" * 40)  # Separator line between results
```

### Running the Code

To run the code, execute the following command in your terminal:

```bash
python main.py
```

Here is an example output for the search query "What is Python?":

```
Document 1 inserted.
Document 2 inserted.
Document 3 inserted.
Document 4 inserted.
Document 5 inserted.
Search Results:
ID: 1
Score: 0.9080
Metadata: {'text': 'Python is a popular programming language.'}
----------------------------------------
ID: 2
Score: 0.7592
Metadata: {'text': 'Machine learning enables computers to learn from data.'}
----------------------------------------
ID: 4
Score: 0.7388
Metadata: {'text': 'Semantic search is a technique for understanding the meaning of queries.'}
----------------------------------------
```

### Code Breakdown

1. **Environment Setup**: We use `python-dotenv` to load our environment variables and use the `Index.from_env()` method to initialize the index client.

2. **Document Insertion**: We define a list of documents, each with a unique ID and text content. The `upsert()` function inserts these documents into our index. These documents are automatically converted into embeddings. To learn more about Upstash Embedding Models, you can check out [this page](https://docs.upstash.com/vector/features/embeddingmodels).

3. **Index Reset**: Before inserting documents, the `reset()` function clears any existing data in the index.

4. **Search Query**: After inserting the documents, we perform semantic search. The `query()` function returns the `top_k` most similar documents to the query along with their metadata if `include_metadata` is set to `True`.

# Examples
Source: https://upstash.com/docs/workflow/agents/examples

Explore our collection of examples to learn how to build robust agent systems. From architectural patterns to real-world implementations, these examples demonstrate the full potential of our Agents API.

## Real World Examples

Practical implementations demonstrating how to use our Agents API in production scenarios. These examples provide ready-to-use templates for common use cases.

<CardGroup cols={2}>
  <Card
    title="Browser Automation"
    icon="globe"
    href="https://github.com/upstash/workflow-js/blob/main/examples/agents/app/agentic-browser-search/route.ts"
  >
    Autonomous web navigation and interaction system for content extraction and
    form handling.
  </Card>
  <Card
    title="Email Analyzer"
    icon="envelope"
    href="https://github.com/upstash/workflow-js/blob/main/examples/agents/app/email-analyzer/route.ts"
  >
    Intelligent email processing system for content analysis, classification,
    and automated responses.
  </Card>
  <Card
    title="Social Media Manager"
    icon="share-nodes"
    href="https://github.com/upstash/workflow-js/blob/main/examples/agents-instagram-post-generator"
  >
    Multi-platform social media management system for content moderation and
    engagement automation.
  </Card>
</CardGroup>

# Features
Source: https://upstash.com/docs/workflow/agents/features

On this page, we explain the features of the Workflow Agents API in more detail.

Prerequisites:
* Setup your first Agent endpoint by following [the Getting Started page](/docs/workflow/agents/getting-started).
* Install the following packages to define tools:

```bash
npm i ai mathjs zod @agentic/ai-sdk @agentic/weather @langchain/core @langchain/community
```

## Models

The `model` is responsible for deciding which tools to call and generating the final response

First, add `QSTASH_TOKEN` and `OPENAI_API_KEY` to your environment:

```
QSTASH_TOKEN="<QSTASH_TOKEN>"
OPENAI_API_KEY="<OPENAI_API_KEY>"
```

Next, define the model in your route:

```ts
import { serve } from "@upstash/workflow/nextjs";
import { agentWorkflow } from "@upstash/workflow-agents";

export const { POST } = serve(async (context) => {
  const agents = agentWorkflow(context);
  const model = agents.openai('gpt-3.5-turbo')

// ...
})
```

If you want to use an OpenAI compatible provider, you can do so by passing `baseURL` and `apiKey`:

```ts
const model = agents.openai('deepseek-chat', {
  baseURL: "https://api.deepseek.com",
  apiKey: process.env.DEEPSEEK_API_KEY
})
```

If you want to use other providers available on AI SDK, you can import the `create<Provider>` methods exported from provider packages. For example, in order to use Anthropic you can do the following:

```ts
import { createAnthropic } from "@ai-sdk/anthropic";

const model = agents.AISDKModel({
  context,
  provider: createAnthropic,
  providerParams: {
    apiKey: "<ANTHROPIC_API_KEY>",
  },
});
```

If you want to configure the calls made to the LLM APIs, you can use the `agentCallParams` parameter:

```ts
const model = agents.openai('gpt-3.5-turbo', {
  callSettings: {
    timeout: 1000, // optional request timeout
    retries: 0,    // optional retries
    flowControl: { // optional flow control
      key: "flow-control-key",
      rate: 10,
      period: "10s",
      parallelism: 10,
    },
  }
})
```

Same parameter is available in `agents.AISDKModel` as the `agentCallParams` parameter.

## Tools

Next, we will define the tools that our agents will use. The **Agents API** is compatible with both **AI SDK** and **LangChain** tools. This means you can either:

* Use existing tools that are compatible with these SDKs.
* Define your own custom tools that are compatible with these SDKs.

This flexibility allows you to tailor the tools to your specific needs while leveraging the power of these frameworks.

```ts WorkflowTool (custom)
import { WorkflowTool } from '@upstash/workflow'
import { z } from 'zod'
import * as mathjs from 'mathjs'

const tool = new WorkflowTool({
  description:
    'A tool for evaluating mathematical expressions. ' +
    'Example expressions: ' +
    "'1.2 * (2 + 4.5)', '12.7 cm to inch', 'sin(45 deg) ^ 2'.",
  schema: z.object({ expression: z.string() }),
  invoke: async ({ expression }) => mathjs.evaluate(expression),
})
```

```ts AI SDK (custom)
import { z } from 'zod'
import { tool } from 'ai'
import * as mathjs from 'mathjs'

const mathTool = tool({
  description:
    'A tool for evaluating mathematical expressions. ' +
    'Example expressions: ' +
    "'1.2 * (2 + 4.5)', '12.7 cm to inch', 'sin(45 deg) ^ 2'.",
  parameters: z.object({ expression: z.string() }),
  execute: async ({ expression }) => mathjs.evaluate(expression),
})
```

```ts Agentic
import { createAISDKTools } from '@agentic/ai-sdk'
import { WeatherClient } from '@agentic/weather'

const weather = new WeatherClient()
const tools = createAISDKTools(weather)
```

```ts LangChain (custom)
import { DynamicStructuredTool } from "@langchain/core/tools";

const numberGenerator = new DynamicStructuredTool({
  name: "random-number-generator",
  description: "generates a random number between two input numbers",
  schema: z.object({
    low: z.number().describe("The lower bound of the generated number"),
    high: z.number().describe("The upper bound of the generated number"),
  }),
  func: async ({ low, high }) =>
    (Math.random() * (high - low) + low).toString(), // Outputs still must be strings
})
```

```ts LangChain
import { WikipediaQueryRun } from '@langchain/community/tools/wikipedia_query_run'

const wikiTool = new WikipediaQueryRun({
  topKResults: 1,
  maxDocContentLength: 500,
})
```

</CodeGroup>

For available toolkits, you can explore the [LangChain Toolkits](https://js.langchain.com/v0.1/docs/modules/agents/tools/toolkits/) or other AI SDK-compatible toolkits like [Agentic](https://agentic.so/sdks/ai-sdk).

By default, the Workflow SDK will wrap the execute/invoke methods of the tools you pass with [`context.run`](/docs/workflow/basics/context#context-run) to run them as a Workflow step. This means, you can't use steps like context.call, context.notify etc in execute/invoke right away. If you want to define steps in invoke/execute, you can use the `executeAsStep` option:

```ts {12}
import { WorkflowTool } from '@upstash/workflow'
import { serve } from '@upstash/workflow/nextjs'

export const { POST } = serve(async (context) => {
  const tool = new WorkflowTool({
    description: ...,
    schema: ...,
    invoke: ( ... ) => {
      // make HTTP call inside the tool with context.call:
      await context.call( ... )
    },
    executeAsStep: false
  })

// pass the tool to agent
})
```

## Agents

After defining a model and tools, we can define agents. Agents are essentially LLM models with access to a set of tools and background knowledge. In Upstash Workflow, agents are defined like this:

```ts route.ts
import { serve } from "@upstash/workflow/nextjs";
import { agentWorkflow } from "@upstash/workflow-agents";
import { WikipediaQueryRun } from "@langchain/community/tools/wikipedia_query_run";

export const { POST } = serve(async (context) => {
  const agents = agentWorkflow(context);
  const model = agents.openai('gpt-3.5-turbo')

const researcherAgent = agents.agent({
    model,
    name: 'academic',
    maxSteps: 2,
    tools: {
      wikiTool: new WikipediaQueryRun({
        topKResults: 1,
        maxDocContentLength: 500,
      })
    },
    background:
      'You are researcher agent with access to Wikipedia. ' +
      'Utilize Wikipedia as much as possible for correct information',
  })
})
```

The parameters for defining an agent are as follows:

* **`model`**: The LLM model that the agent will use.
* **`name`**: The name of the agent. This name will be used when naming the [context.call steps](/docs/workflow/basics/context#context-call) for this agent. `context.call` is used when calling the LLM provider (such as OpenAI).
* **`maxSteps`**: The maximum number of times this agent can call the LLM provider (e.g., OpenAI).
* **`tools`**: The list of tools available to the agent for completing tasks.
* **`background`**: A description of the agent, which is used as a system prompt to provide context for the agent's behavior.

## Tasks

Now that we have agents defined, the only thing left is to assign tasks to them. A **task** is simply a prompt passed to the agent.

There are two ways to create a task:

1. **Single Agent Task**: The task is assigned to a single agent, which will complete it using the tools available to it.

2. **Multiple Agent Task**: A **manager agent** is used to decide which agents will be involved and in what order. The manager agent makes this decision based on the task prompt, the agents' backgrounds, and the tools available to them.

### Single Agent

```ts Single Agent {22-27}
import { serve } from "@upstash/workflow/nextjs";
import { agentWorkflow } from "@upstash/workflow-agents";
import { WikipediaQueryRun } from "@langchain/community/tools/wikipedia_query_run";

export const { POST } = serve(async (context) => {
  const agents = agentWorkflow(context);
  const model = agents.openai('gpt-3.5-turbo');

const task = agents.task({
    agent: researcherAgent,
    prompt: "Tell me about 5 topics in advanced physics.",
  });
  const { text } = await task.run();
  console.log("result:", text)
})
```

As response to the task, the agent generates the following response:

```
Here are summaries of 5 topics in advanced physics:

1. **Quantum Mechanics**: Quantum mechanics is a fundamental theory that describes the behavior of nature at and below the scale of atoms. It is the foundation of all quantum physics, including quantum chemistry, quantum field theory, quantum technology, and quantum information science. Quantum mechanics can describe many systems that classical physics cannot.

2. **General Relativity**: General relativity, also known as Einstein's theory of gravity, is the geometric theory of gravitation published by Albert Einstein in 1915. It is the current description of gravitation in modern physics, generalizing special relativity and refining Newton's law of universal gravitation. General relativity provides a unified description of gravity as a geometric property of space and time.

3. **Particle Physics**: Particle physics, also known as high-energy physics, is the study of fundamental particles and forces that constitute matter and radiation. The field also studies combinations of elementary particles up to the scale of protons and neutrons. Fundamental particles in the universe are classified in the Standard Model as fermions (matter particles) and bosons (force-carrying particles).

4. **Astrophysics**: Astrophysics is a science that applies the methods and principles of physics and chemistry to the study of astronomical objects and phenomena. It seeks to ascertain the nature of heavenly bodies and is distinct from celestial mechanics, which focuses on the positions and motions of objects in space. Subjects studied in astrophysics include the Sun, stars, galaxies, and the universe.

5. **String Theory**: String theory is a theoretical framework in physics where point-like particles are replaced by one-dimensional objects called strings. These strings describe how they propagate through space and interact with each other. On distance scales larger than the string scale, a string behaves like a particle, with its properties determined by the vibrational state of the string
```

Here is the logs on Upstash Console:

<img />

In the logs, you can see that the **academic agent** was called. It decided to invoke **wikiTool** five times in parallel. Once the tool requests were completed, the agent summarized the results from the individual calls in one final response and returned the outcome.

### Multi Agents

```ts Multi Agents {45-53}
import { serve } from "@upstash/workflow/nextjs";
import { agentWorkflow } from "@upstash/workflow-agents";
import { WikipediaQueryRun } from "@langchain/community/tools/wikipedia_query_run";
import * as mathjs from 'mathjs'
import { tool } from "ai";
import { z } from "zod";

export const { POST } = serve(async (context) => {
  const agents = agentWorkflow(context);
  const model = agents.openai('gpt-4o');

const mathAgent = agents.agent({
    model,
    name: "mathematician",
    maxSteps: 2,
    tools: {
      calculate: tool({
        description:
          'A tool for evaluating mathematical expressions. ' +
          'Example expressions: ' +
          "'1.2 * (2 + 4.5)', '12.7 cm to inch', 'sin(45 deg) ^ 2'." +
          "only call this tool if you need to calculate a mathematical expression." +
          "when writing an expression, don't use words like 'thousand' or 'million'",
        parameters: z.object({ expression: z.string() }),
        execute: async ({ expression }) => mathjs.evaluate(expression),
      }),
    },
    background:
      "You are a mathematician agent which can utilize" +
      "a calculator to compute expressions"
  })

const task = agents.task({
    model,
    maxSteps: 3,
    agents: [researcherAgent, mathAgent],
    prompt: "Tell me about 3 cities in Japan and calculate the sum of their populations",
  });
  const { text } = await task.run();
  console.log("result:", text)
})
```

As response to the task, the agents generate the following response:

```
Here is a brief overview of three cities in Japan:

### Tokyo
- **Official Name**: Tokyo Metropolis
- **Population**: Over 14 million in the city proper as of 2023.
- **Significance**: Capital of Japan and one of the most populous urban areas in the world.

### Osaka
- **Japanese Name**: å¤§éå¸ (Åsaka-shi)
- **Population**: 2.7 million as per the 2020 census.
- **Significance**: Capital and most populous city in Osaka Prefecture, third-most populous city in Japan.

### Kyoto
- **Japanese Name**: äº¬é½å¸ (KyÅto-shi)
- **Population**: 1.46 million as of 2020.
- **Significance**: Capital city of Kyoto Prefecture, ninth-most populous city in Japan.

The sum of their populations is approximately 18.16 million.
```

Here are the logs on Upstash Console:

<img />

The logs show that the `Manager LLM` first called the `academic` agent. The `academic` agent used the `wikiTool` three times, each with a different Japanese city, and summarized the results. Next, the `Manager LLM` called the `mathematician` agent, which used its `calculate` tool to compute the total population of the three cities and returned the result to the `Manager LLM`. With information about the cities and their total population, the `Manager LLM` generated the final response.

# Getting Started
Source: https://upstash.com/docs/workflow/agents/getting-started

In this guide, we will be using **Next.js**. If you're working with a different supported framework, you can find instructions on how to define a workflow endpoint in the [quickstarts](/docs/workflow/quickstarts/platforms).

If you're new to **Upstash Workflow**, it's a good idea to start by exploring the [Local Development documentation](/docs/workflow/howto/local-development). This guide will help you set up and use Upstash Workflow in a local environment.

##  Installation

First, create a new Next.js project with:

```
npx create-next-app@latest [project-name] [options]
```

Then, install the following packages:

```
npm i @upstash/workflow @upstash/workflow-agents ai zod
```

## Start Local QStash Server

Next, start the local QStash server with the following:

```bash npm
npx @upstash/qstash-cli dev
```
```bash pnpm
pnpm dlx @upstash/qstash-cli dev
```
</CodeGroup>

For other local development options, you can refer to [the local development documentation](/docs/workflow/howto/local-development).

## Set Environment Variables

Once you start the QStash server, you’ll see `QSTASH_URL` and `QSTASH_TOKEN` values in the console. Add these values to your `.env.local` file together with `OPENAI_API_KEY` env variable:

```txt .env.local
QSTASH_URL="http://127.0.0.1:8080"
QSTASH_TOKEN="<QSTASH_TOKEN>"

OPENAI_API_KEY=<OPENAI_API_KEY>
```

## Define an endpoint

Next, we will define the endpoint to run the agent.

```ts app/workflow/route.ts
import { z } from "zod";
import { tool } from "ai";

import { serve } from "@upstash/workflow/nextjs";
import { agentWorkflow } from "@upstash/workflow-agents";

export const { POST } = serve<{ prompt: string }>(async (context) => {
  const prompt = context.requestPayload.prompt
  const agents = agentWorkflow(context)
  const model = agents.openai('gpt-3.5-turbo')

const communicatorAgent = agents.agent({
    model,
    name: 'communicatorAgent',
    maxSteps: 2,
    tools: {
      communicationTool: tool({
        description: 'A tool for informing the caller about your inner thoughts',
        parameters: z.object({ message: z.string() }),
        execute: async ({ message }) => {
          console.log("Inner thought:", message)
          return "success"
        }
      })
    },
    background:
      'Answer questions directed towards you.' +
      ' You have access to a tool to share your inner thoughts' +
      ' with the caller. Utilize this tool at least once before' +
      ' answering the prompt. In your inner thougts, briefly' +
      ' explain what you will talk about and why. Keep your' +
      ' answers brief.',
  })

const task = agents.task({
    agent: communicatorAgent,
    prompt
  })

const { text } = await task.run()

console.log("Final response:", text);
})
```

You can refer to the documentations for [defining a workflow endpoint](/docs/workflow/basics/serve) and [the Agents API features](/docs/workflow/agents/features) to learn more.

## Calling the Endpoint

To run the endpoint, first run the Next.js app with:

```bash
npm run dev
```

Then, we call the endpoint using [the Workflow Client](/docs/workflow/basics/client):

```ts
import { Client } from "@upstash/workflow";

const client = new Client({
  baseUrl: process.env.QSTASH_URL,
  token: process.env.QSTASH_TOKEN!,
})

const workflowRunId = await client.trigger({
  url: "http://127.0.0.1:3000/workflow",
  body: { prompt: "Explain the future of space exploration" }
})

console.log(workflowRunId);
```

<Tip>
  If you are using a local tunnel, replace the url above (`http://127.0.0.1:3000`)
  with the public URL.
</Tip>

In the console where you run the Next.js app, you should see logs like this:

```
Inner thought: I will discuss the future of space
exploration and the potential advancements in
technology and missions.

Final response: The future of space exploration
holds exciting possibilities with advancements
in technology, potential manned missions to
Mars, increased commercial space travel,
and exploration of distant celestial
bodies.
```

If you [run the same endpoint using a local tunnel](/docs/workflow/howto/local-development#local-tunnel-with-ngrok), you can also see how Upstash Workflow runs the agent in steps:

<img />

Each tool invocation and LLM call is a seperate step. Our agent first made a call to OpenAI to decide whether to use a tool or reply right away. OpenAI responded with a request to use the tool `communicationTool`. Tool was executed and OpenAI was called with the result of the tool. OpenAI then responded with the final response.

# Overview
Source: https://upstash.com/docs/workflow/agents/overview

The **Agents API** of Upstash Workflow enables you to:
* Execute an individual agent or facilitate collaboration among multiple agents.
* Integrate any tool compatible with AI SDK or LangChain.
* Reliably invoke agents without concerns about timeouts or transient errors.
* Unlike mainstream agent frameworks, we prioritize debuggability and extensibility.

To get started, you can refer to the [Getting Started page](/docs/workflow/agents/getting-started). For more details about the features, you can refer to [the Features page](/docs/workflow/agents/features).

<Note>
  This feature is not yet available in
  [workflow-py](https://github.com/upstash/workflow-py). See our
  [Roadmap](/docs/workflow/roadmap) for feature parity plans and
  [Changelog](/docs/workflow/changelog) for updates.
</Note>

## Agent Patterns

If you're interested, you can also explore our rich examples that showcase how various patterns can be built using the Agents API:

<CardGroup cols={2}>
  <Card title="Prompt Chaining" icon="link" href="/workflow/agents/patterns/prompt-chaining">
    Sequential LLM calls where each output becomes the input for the next, enabling structured reasoning and step-by-step task completion.
  </Card>
  <Card title="Evaluator-optimizer" icon="arrows-rotate" href="/workflow/agents/patterns/evaluator-optimizer">
    A feedback loop where LLM outputs are evaluated and refined iteratively to improve accuracy and relevance.
  </Card>
  <Card title="Parallelization" icon="arrows-to-dot" href="/workflow/agents/patterns/parallelization">
    Distribute tasks across multiple LLMs and aggregate the results for efficient handling of complex or large-scale operations.
  </Card>
  <Card title="Orchestrator-workers" icon="sparkles" href="/workflow/agents/patterns/orchestrator-workers">
    A central orchestrator directs multiple worker LLMs to complete subtasks and synthesize their outputs for complex operations.
  </Card>
</CardGroup>

## Real World Examples

Practical implementations demonstrating how to use our Agents API in production scenarios. These examples provide ready-to-use templates for common use cases.

# Evaluator-Optimizer
Source: https://upstash.com/docs/workflow/agents/patterns/evaluator-optimizer

<img />

In this example, the generator creates output and passes it to the evaluator, which evaluates the response. If the evaluation fails, the evaluator returns corrections, and the generator is called again using the corrected output.

```ts
import { serve } from "@upstash/workflow/nextjs";
import { agentWorkflow } from "@upstash/workflow-agents";

export const { POST } = serve(async (context) => {
  const agents = agentWorkflow(context);
  const model = agents.openai('gpt-3.5-turbo');

// Generator agent that generates content
  const generator = agents.agent({
    model,
    name: 'generator',
    maxSteps: 1,
    background: 'You are an agent that generates text based on a prompt.',
    tools: {}
  });

// Evaluator agent that evaluates the text and gives corrections
  const evaluator = agents.agent({
    model,
    name: 'evaluator',
    maxSteps: 1,
    background: 'You are an agent that evaluates the generated text and provides corrections if needed.',
    tools: {}
  });

let generatedText = '';
  let evaluationResult = '';

// Generate content
    const generatedResponse = await agents.task({ agent: generator, prompt: nextPrompt }).run();
    generatedText = generatedResponse.text

// Evaluate the generated content
    const evaluationResponse = await agents.task({ agent: evaluator, prompt: `Evaluate and provide feedback for the following text: ${generatedText}` }).run();
    evaluationResult = evaluationResponse.text

// If the evaluator accepts the content (i.e., "PASS"), stop
    if (evaluationResult.includes("PASS")) {
      break;
    }
  }

console.log(generatedText);
});
```

<img />

In response to the prompt, our agents generate this response:

```
Quantum mechanics is a branch of physics that describes the behavior of particles at the smallest scales, such as atoms and subatomic particles. It introduces the concept of quantized energy levels, wave-particle duality, and probabilistic nature of particles. In quantum mechanics, particles can exist in multiple states simultaneously until measured, and their behavior is governed by mathematical equations known as wave functions. This theory has revolutionized our understanding of the fundamental building blocks of the universe and has led to the development of technologies like quantum computing and quantum cryptography.
```

# Orchestrator-Workers
Source: https://upstash.com/docs/workflow/agents/patterns/orchestrator-workers

<img />

This workflow uses an orchestrator to direct multiple worker agents to handle different subtasks, then synthesizes their outputs.

```ts
import { serve } from "@upstash/workflow/nextjs";
import { agentWorkflow } from "@upstash/workflow-agents";
import { WikipediaQueryRun } from "@langchain/community/tools/wikipedia_query_run";

const wikiTool = new WikipediaQueryRun({
  topKResults: 1,
  maxDocContentLength: 500,
})

export const { POST } = serve(async (context) => {
  const agents = agentWorkflow(context);
  const model = agents.openai('gpt-4o');

// Worker agents
  const worker1 = agents.agent({
    model,
    name: 'worker1',
    tools: { wikiTool },
    maxSteps: 3,
    background: 'You are a worker agent that answers general questions about advanced physics.'
  });

const worker2 = agents.agent({
    model,
    name: 'worker2',
    tools: { wikiTool },
    maxSteps: 3,
    background: 'You are a worker agent that answers questions about quantum mechanics.'
  });

const worker3 = agents.agent({
    model,
    name: 'worker3',
    tools: { wikiTool },
    maxSteps: 3,
    background: 'You are a worker agent that answers questions about relativity.'
  });

// Synthesizing results
  const task = agents.task({
    model,
    prompt: `Create a Q&A for advanced topics in physics`,
    agents: [worker1, worker2, worker3],
    maxSteps: 3,
  })
  const { text } = await task.run();

console.log(text);
});
```

If you wish to manually use the model results instead of utilizing a [manager LLM](/docs/workflow/agents/overview#multi-agents) as we did in this example, see the [parallelization example](/docs/workflow/agents/patterns/parallelization)

<img />

In response to the prompt, the agents create the following response:

```
### Quantum Mechanics

**Q: What is quantum mechanics?**
A: Quantum mechanics is a fundamental theory in physics that describes the behavior of nature at the atomic and subatomic levels. It serves as the foundation for all quantum physics, including quantum chemistry, quantum field theory, quantum technology, and quantum information science.

**Q: What are some key principles of quantum mechanics?**
A:
1. **Wave-Particle Duality**: Particles exhibit both wave-like and particle-like properties.
2. **Uncertainty Principle**: Certain pairs of physical properties, like position and momentum, cannot be simultaneously measured with arbitrary precision.
3. **Quantum Superposition**: A quantum system can exist in multiple states at once until it is measured.
4. **Quantum Entanglement**: Particles become interconnected such that the state of one influences the state of another, regardless of distance.
5. **Quantization**: Energy levels in quantum systems are discrete.
6. **Probability and Wave Functions**: Quantum systems are described by wave functions, which provide probabilities of finding a system in a particular state.
7. **Observer Effect**: Measurement affects the system being observed.

### Relativity

**Q: What is the theory of relativity?**
A: Developed by Albert Einstein, the theory of relativity encompasses two interrelated theories: special relativity and general relativity.

**Q: What is special relativity?**
A: Proposed by Einstein in 1905, special relativity addresses the relationship between space and time in the absence of gravity. It is based on two key postulates: the invariance of physical laws in all inertial frames and the constancy of the speed of light in a vacuum.

**Q: What is general relativity?**
A: Published by Einstein in 1915, general relativity is a geometric theory of gravitation. It describes gravity as a geometric property of space and time, or four-dimensional spacetime, and explains how massive objects cause a distortion in spacetime.

These topics challenge classical intuitions and have led to significant advancements in our understanding of the universe and the development of new technologies.
```

# Parallelization
Source: https://upstash.com/docs/workflow/agents/patterns/parallelization

<img />

This workflow calls multiple agents simultaneously to handle tasks, and then aggregates their results.

```ts
import { serve } from "@upstash/workflow/nextjs";
import { agentWorkflow } from "@upstash/workflow-agents";

export const { POST } = serve(async (context) => {
  const agents = agentWorkflow(context);
  const model = agents.openai('gpt-3.5-turbo');

// Define worker agents
  const worker1 = agents.agent({
    model,
    name: 'worker1',
    maxSteps: 1,
    background: 'You are an agent that explains quantum physics.',
    tools: {}
  });

const worker2 = agents.agent({
    model,
    name: 'worker2',
    maxSteps: 1,
    background: 'You are an agent that explains relativity.',
    tools: {}
  });

const worker3 = agents.agent({
    model,
    name: 'worker3',
    maxSteps: 1,
    background: 'You are an agent that explains string theory.',
    tools: {}
  });

// Await results
  const [result1, result2, result3] = await Promise.all([
    agents.task({ agent: worker1, prompt: "Explain quantum physics." }).run(),
    agents.task({ agent: worker2, prompt: "Explain relativity." }).run(),
    agents.task({ agent: worker3, prompt: "Explain string theory." }).run(),
  ]);

// Aggregating results
  const aggregator = agents.agent({
    model,
    name: 'aggregator',
    maxSteps: 1,
    background: 'You are an agent that summarizes multiple answers.',
    tools: {}
  });

const task = await agents.task({
    agent: aggregator,
    prompt: `Summarize these three explanations: ${result1.text}, ${result2.text}, ${result3.text}`
  })
  const finalSummary = await task.run();

console.log(finalSummary.text);
});

```

You can also see how the same thing can be achieved using an manager agent in [orchestrator-workers example](/docs/workflow/agents/patterns/orchestrator-workers).

<img />

In response to the prompt, our agents generate this response:

```
Quantum physics explores the behavior of very small particles, such as atoms and subatomic particles, in the strange world of quantum mechanics, where particles can exist in multiple states simultaneously. Key principles include superposition and entanglement, leading to technological advancements like quantum computers. Relativity, developed by Albert Einstein, consists of special relativity and general relativity, explaining the behavior of objects moving at high speeds and the warping of spacetime by massive objects. String theory proposes that the universe's fundamental building blocks are tiny vibrating strings, aiming to unify the four fundamental forces of nature and suggest extra dimensions beyond the familiar ones.
```

# Prompt Chaining
Source: https://upstash.com/docs/workflow/agents/patterns/prompt-chaining

<img />

This workflow involves chaining multiple LLM calls, where the output of one agent becomes the input for the next agent.

```ts
import { serve } from "@upstash/workflow/nextjs";
import { agentWorkflow } from "@upstash/workflow-agents";
import { WikipediaQueryRun } from "@langchain/community/tools/wikipedia_query_run";

export const { POST } = serve(async (context) => {
  const agents = agentWorkflow(context);
  const model = agents.openai('gpt-3.5-turbo');

const agent1 = agents.agent({
    model,
    name: 'firstAgent',
    maxSteps: 1,
    background: 'You are an agent that lists famous physicists.',
    tools: {}
  });

const agent2 = agents.agent({
    model,
    name: 'secondAgent',
    // set to 2 as this agent will first request tools
    // and then summarize them:
    maxSteps: 2,
    background:
      'You are an agent that describes the work of' +
      ' the physicists listed in the previous prompt.',
    tools: {
      wikiTool: new WikipediaQueryRun({
        topKResults: 1,
        maxDocContentLength: 500,
      })
    }
  });

const agent3 = agents.agent({
    model,
    name: 'thirdAgent',
    maxSteps: 1,
    background:
      'You are an agent that summarizes the ' +
      'works of the physicists mentioned previously.',
    tools: {}
  });

// Chaining agents
  const firstOutput = await agents.task({
    agent: agent1,
    prompt: "List 3 famous physicists."
  }).run();

const secondOutput = await agents.task({
    agent: agent2,
    prompt: `Describe the work of: ${firstOutput.text}`
  }).run();

const { text } = await agents.task({
    agent: agent3,
    prompt: `Summarize: ${secondOutput.text}`
  }).run();

console.log(text);
});
```

<img />

In response to the prompt, our agents generate this response:

```
Albert Einstein was a German physicist known for his theory of relativity and the famous equation E=mc^2. He made significant contributions to quantum mechanics and was awarded the Nobel Prize in Physics in 1921.

Isaac Newton, an English polymath, was a key figure in the Scientific Revolution and the Enlightenment. He is famous for his laws of motion and universal gravitation, as outlined in his book "PhilosophiÃ¦ Naturalis Principia Mathematica."

Marie Curie, a Polish-French physicist and chemist, conducted pioneering research on radioactivity and was the first woman to win a Nobel Prize. She is the only person to win Nobel Prizes in two scientific fields and her work has had a lasting impact on physics and chemistry.
```

# Bulk Delete Failed Workflow Runs
Source: https://upstash.com/docs/workflow/api-reference/dlq/bulk-delete-failed-workflow-runs

/workflow/openapi.yaml delete /v2/workflows/dlq
Delete multiple failed workflow runs from the DLQ.

When a workflow run fails, it is moved to the DLQ. You can manually remove a failed workflow run from the DLQ using this endpoint. This is useful for cleaning up failed runs that you no longer wish to retry or analyze.

You can either specify specific DLQ IDs to delete, or use filters to delete matching workflows.
When using filters without DLQ IDs, the operation supports pagination via cursor.

# Bulk Restart Workflows from DLQ
Source: https://upstash.com/docs/workflow/api-reference/dlq/bulk-restart-workflows-from-dlq

/workflow/openapi.yaml post /v2/workflows/dlq/restart
Restart multiple failed workflow runs from the DLQ. Each workflow will start from the beginning.

Unlike resume, which continues from where workflows failed, restart executes the entire workflows
from the first step. New workflow run IDs are generated and all steps will be executed again.

A maximum of 50 workflow runs can be restarted per request. If more runs are available, a cursor is returned, which can be used in subsequent requests to continue the operation. When no cursor is returned, all entries have been processed.
Each restarted workflow run is assigned a new random Run ID.

# Bulk Resume Workflows from DLQ
Source: https://upstash.com/docs/workflow/api-reference/dlq/bulk-resume-workflows-from-dlq

/workflow/openapi.yaml post /v2/workflows/dlq/resume
When a workflow run fails, it's automatically moved to the DLQ (Dead Letter Queue) where it can be analyzed and resumed. 
  The resume feature allows you to continue a failed workflow run from exactly where it failed, without re-executing successfully completed steps.

This is particularly useful for long-running workflows where you don't want to lose progress from successful steps when a single step fails.

When a workflow is resumed, it continues execution from the last failed step. A new workflow run ID is generated,
  but the workflow maintains the state and results from previously completed steps.

<Note>
    You can make changes to the workflow code as long as these changes come after the failed steps. 
    However, making changes before the failed step will break the code and is not allowed.

For more details, check out [Handle workflow route code changes](/docs/workflow/howto/changes) page.
  </Note>

# Cancel In-Progress Failure Callback
Source: https://upstash.com/docs/workflow/api-reference/dlq/cancel-in-progress-failure-callback

/workflow/openapi.yaml delete /v2/workflows/dlq/callback/{dlqId}
Cancel an in-progress failure callback for a failed workflow.

When you retry a failed failure callback using the POST endpoint, it enters an in-progress state.
This endpoint allows you to cancel that in-progress callback before it completes.

The callback must be in an in-progress state. If there's no in-progress callback,
the request will fail with a 400 error.

# Delete Failed Workflow Run
Source: https://upstash.com/docs/workflow/api-reference/dlq/delete-failed-workflow-run

/workflow/openapi.yaml delete /v2/workflows/dlq/{dlqId}
Delete a specific failed workflow run from the DLQ.

Use this endpoint to remove a workflow from the DLQ after you have addressed the issue
or determined that the workflow should not be retried.

# Get Failed Workflow Run
Source: https://upstash.com/docs/workflow/api-reference/dlq/get-failed-workflow-run

/workflow/openapi.yaml get /v2/workflows/dlq/{dlqId}
Get details of a specific failed workflow run from the DLQ.

# List Failed Workflow Runs
Source: https://upstash.com/docs/workflow/api-reference/dlq/list-failed-workflow-runs

/workflow/openapi.yaml get /v2/workflows/dlq
List and paginate through all failed workflow runs currently in the DLQ.

Failed workflows end up in the DLQ after exhausting all retry attempts. You can filter,
paginate, and inspect these failures to understand what went wrong and decide whether to
resume, restart, or delete them.

# Restart Workflow from DLQ
Source: https://upstash.com/docs/workflow/api-reference/dlq/restart-workflow-from-dlq

/workflow/openapi.yaml post /v2/workflows/dlq/restart/{dlqId}
Restart a failed workflow run from the DLQ. The workflow will start from the beginning.

Unlike resume, which continues from where the workflow failed, restart executes the entire workflow
from the first step. A new workflow run ID is generated and all steps will be executed again.

# Resume Workflow from DLQ
Source: https://upstash.com/docs/workflow/api-reference/dlq/resume-workflow-from-dlq

/workflow/openapi.yaml post /v2/workflows/dlq/resume/{dlqId}

# Retry Failure Callback
Source: https://upstash.com/docs/workflow/api-reference/dlq/retry-failure-callback

/workflow/openapi.yaml post /v2/workflows/dlq/callback/{dlqId}
If the failure callback for a workflow run has failed, you can use this endpoint to manually trigger the failure callback again. 
This is useful for ensuring that your system is notified of workflow failures even if the original callback attempt did not succeed.

The state of the failure callback for each workflow run is included in the DLQ message response as failureCallbackInfo.state. 
You can filter for all workflow runs with a failed failure callback by using the failureCallbackState filter when listing workflow runs in the DLQ with the `/v2/workflows/dlq` endpoint.

# Get Flow Control Key
Source: https://upstash.com/docs/workflow/api-reference/flow-control/get-flow-control-key

/workflow/openapi.yaml get /v2/flowControl/{flowControlKey}
Get details of a specific Flow Control key

# Get Flow Control Key
Source: https://upstash.com/docs/workflow/api-reference/flow-control/get-flow-control-key-1

/workflow/openapi.yaml get /v2/keys/rotate
Get details of a specific Flow Control key.

Flow Control keys are used to manage concurrency and rate limiting for workflow steps.
This endpoint returns the current waitlist size for the specified flow control key,
which indicates how many workflow steps are currently waiting due to flow control constraints.

# Get Global Parallelism
Source: https://upstash.com/docs/workflow/api-reference/flow-control/get-global-parallelism

/workflow/openapi.yaml get /v2/globalParallelism
Returns the current global parallelism usage across all flow control keys

# List Flow Control Keys
Source: https://upstash.com/docs/workflow/api-reference/flow-control/list-flow-control-keys

/workflow/openapi.yaml get /v2/flowControl
List all Flow Control keys

# Pause Flow Control Key
Source: https://upstash.com/docs/workflow/api-reference/flow-control/pause-flow-control-key

/workflow/openapi.yaml post /v2/flowControl/{flowControlKey}/pause
Pauses the delivery of messages associated with a specific flow-control key.

# Pin Configuration for Flow Control Key
Source: https://upstash.com/docs/workflow/api-reference/flow-control/pin-configuration-for-flow-control-key

/workflow/openapi.yaml post /v2/flowControl/{flowControlKey}/pin
Pins a processing configuration for a specific flow-control key.

# Reset Rate for Flow Control Key
Source: https://upstash.com/docs/workflow/api-reference/flow-control/reset-rate-for-flow-control-key

/workflow/openapi.yaml post /v2/flowControl/{flowControlKey}/resetRate
Resets the rate configuration state for a specific flow-control key.

# Resume Flow Control Key
Source: https://upstash.com/docs/workflow/api-reference/flow-control/resume-flow-control-key

/workflow/openapi.yaml post /v2/flowControl/{flowControlKey}/resume
Resumes the delivery of messages associated with a specific flow-control key.

# Unpin Configuration for Flow Control Key
Source: https://upstash.com/docs/workflow/api-reference/flow-control/unpin-configuration-for-flow-control-key

/workflow/openapi.yaml post /v2/flowControl/{flowControlKey}/unpin
Removes the pinned configuration for a specific flow-control key.

# List Workflow Run Logs
Source: https://upstash.com/docs/workflow/api-reference/logs/list-workflow-run-logs

/workflow/openapi.yaml get /v2/workflows/logs

# List Waiters
Source: https://upstash.com/docs/workflow/api-reference/notify/list-waiters

/workflow/openapi.yaml get /v2/waiters/{eventId}
List all active waiters for a specific event ID.

Returns information about all workflow runs that are currently waiting for the specified event.

# Notify Event
Source: https://upstash.com/docs/workflow/api-reference/notify/notify-event

/workflow/openapi.yaml post /v2/notify/{eventId}
Notify an event to all waiters listening for that event ID.

This endpoint broadcasts an event to all active waiters that are waiting for the specified event.
Each waiting workflow step receives the event data and continues execution.

**Important:** This is an "unsafe notify" operation - if there are no active waiters when the
notification is sent, the event is lost and will not be delivered later. For guaranteed delivery
within a specific workflow run, use the `/v2/notify/{workflowRunId}/{eventId}` endpoint instead.

# Notify Workflow Run Event
Source: https://upstash.com/docs/workflow/api-reference/notify/notify-workflow-run-event

/workflow/openapi.yaml post /v2/notify/{workflowRunId}/{eventId}
Notify an event to a specific workflow run's waiters.

This endpoint sends an event notification to waiters within a specific workflow run.
Unlike the general notify endpoint, this uses a "safe notify" mechanism that guarantees
delivery even if no waiter is currently active.

**Safe Notify Behavior:**
- If a waiter is currently active, it receives the notification immediately
- If no waiter is active, the notification is saved in the database
- When a waiter becomes active later, it will consume the saved notification
- This ensures events are never lost due to timing issues

# Batch Trigger Workflow Runs
Source: https://upstash.com/docs/workflow/api-reference/runs/batch-trigger-workflow-runs

/workflow/openapi.yaml post /v2/batch/trigger
Start multiple workflow runs in a single request.

# Bulk Cancel Workflow Runs
Source: https://upstash.com/docs/workflow/api-reference/runs/bulk-cancel-workflow-runs

/workflow/openapi.yaml delete /v2/workflows/runs
Cancel all matching workflow runs.

# Cancel Workflow Run
Source: https://upstash.com/docs/workflow/api-reference/runs/cancel-workflow-run

/workflow/openapi.yaml delete /v2/workflows/runs/{workflowRunId}
Cancel an ongoing workflow run.

# Trigger Workflow Run
Source: https://upstash.com/docs/workflow/api-reference/runs/trigger-workflow-run

/workflow/openapi.yaml post /v2/trigger/{workflowUrl}
Start a new workflow run.

# Get Signing Keys
Source: https://upstash.com/docs/workflow/api-reference/signing-keys/get-signing-keys

/workflow/openapi.yaml get /v2/keys
Retrieve your current and next signing keys

# Rotate Signing Keys
Source: https://upstash.com/docs/workflow/api-reference/signing-keys/rotate-signing-keys

/workflow/openapi.yaml post /v2/keys/rotate
Rotate your signing keys

# Caveats
Source: https://upstash.com/docs/workflow/basics/caveats

## Introduction

In this guide, we'll look at best practices and caveats for using Upstash Workflow.

## Core Principles

### Execute business logic in `context.run`

Your workflow endpoint will be called multiple times during a workflow run. Therefore:

* Place your business logic code inside the `context.run` function for each step
* Code outside `context.run` only serves to connect steps

Example:

```typescript api/workflow/route.ts
export const { POST } = serve<string>(async (context) => {
  const input = context.requestPayload

const result = await context.run("step-1", () => {
    return { success: true }
  })

console.log("This log will appear multiple times")

await context.run("step-2", () => {
    console.log("This log will appear just once")
    console.log("Step 1 status is:", result.success)
  })
})
```

```python main.py
@serve.post("/api/example")
async def example(context: AsyncWorkflowContext[str]) -> None:
    input = context.request_payload

async def _step_1() -> Dict:
        return {"success": True}

result = await context.run("step-1", _step_1)

print("This log will appear multiple times")

async def _step_2() -> None:
        print("This log will appear just once")
        print("Step 1 status is:", result["success"])

await context.run("step-2", _step_2)

```

</CodeGroup>

### Return Results from context.run for Later Use

Always return step results if needed in subsequent steps.

```typescript ❌ Incorrect - TypeScript
export const { POST } = serve<string>(async (context) => {
  const input = context.requestPayload

let result

await context.run("step-1", async () => {
    result = await someWork(input)
  })
  await context.run("step-2", async () => {
    await someOtherWork(result)
  })
})
```

```typescript ✅ Correct - TypeScript
export const { POST } = serve<string>(async (context) => {
  const input = context.requestPayload

const result = await context.run("step-1", async () => {
    return await someWork(input)
  })

await context.run("step-2", async () => {
    someOtherWork(result)
  })
})
```

```python ❌ Incorrect - Python
@serve.post("/api/example")
async def example(context: AsyncWorkflowContext[str]) -> None:
    input = context.request_payload

result = None

async def _step_1() -> Dict:
        nonlocal result
        result = await some_work(input)

await context.run("step-1", _step_1)

async def _step_2() -> None:
        await some_other_work(result)

await context.run("step-2", _step_2)

```

```python ✅ Correct - Python
@serve.post("/api/example")
async def example(context: AsyncWorkflowContext[str]) -> None:
    input = context.request_payload

async def _step_1() -> Dict:
        return await some_work(input)

result = await context.run("step-1", _step_1)

async def _step_2() -> None:
        await some_other_work(result)

await context.run("step-2", _step_2)

```

</CodeGroup>

Because your workflow endpoint is called multiple times, `result` will be unitialized when the endpoint is called again to run `step-2`.

If you are curious about why an endpoint is called multiple times, see [how Workflow works](/docs/workflow/basics/how).

## Avoiding Common Pitfalls

### Avoid Non-deterministic Code Outside `context.run`

A workflow endpoint should always produce the same results, even if it's called multiple times. Avoid:

* Non-idempotent functions
* Time-dependent code
* Randomness

Example of what to avoid:

```typescript ❌ Non-idempotent functions - TypeScript
export const { POST } = serve<{ entryId: string }>(async (context) => {
  const { entryId } = context.requestPayload;

// 👇 Problem: Non-idempotent function outside context.run:
  const result = await getResultFromDb(entryId);
  if (result.return) {
    return;
  }

// ...
})
```

```typescript ❌ Time-dependent code - TypeScript
export const { POST } = serve<string>(async (context) => {
  const input = context.requestPayload

// 👇 Problem: time-dependent code
  if (Date.now() % 5 == 2) {
    await context.run("step-1", () => {
      // ...
    })
  } else {
    await context.run("step-2", () => {
      // ...
    })
  }
})
```

```typescript ❌ Random code - TypeScript
export const { POST } = serve<string>(async (context) => {
  const input = context.requestPayload

// 👇 Problem: random code
  if (Math.floor(Math.random() * 10) % 5 == 2) {
    await context.run("step-1", () => {
      // ...
    })
  } else {
    await context.run("step-2", () => {
      // ...
    })
  }
})
```

```python ❌ Non-idempotent functions - Python
@serve.post("/api/example")
async def example(context: AsyncWorkflowContext[str]) -> None:
    entry_id = context.request_payload["entry_id"]

# 👇 Problem: Non-idempotent function outside context.run:
    result = await get_result_from_db(entry_id)
    if result.should_return:
        return

# ...

```

```python ❌ Time-dependent code - Python
@serve.post("/api/example")
async def example(context: AsyncWorkflowContext[str]) -> None:
    input = context.request_payload

# 👇 Problem: time-dependent code
    if time.time() % 5 == 2:
        await context.run("step-1", lambda: ...)
    else:
        await context.run("step-2", lambda: ...)

```

```python ❌ Random code - Python
@serve.post("/api/example")
async def example(context: AsyncWorkflowContext[str]) -> None:
    input = context.request_payload

# 👇 Problem: random code
    if random.randint(0, 9) % 5 == 2:
        await context.run("step-1", lambda: ...)
    else:
        await context.run("step-2", lambda: ...)

```

</CodeGroup>

If you implement a non-idempotent code like the one shown above, you might encounter `Failed to authenticate Workflow request.` errors. This can happen if you `return` based on the result of the non-idempotent code before any workflow step.

To prevent this, ensure that the non-idempotent code (such as `getResultFromDb` in the example) runs within `context.run`.

```typescript TypeScript
const result = await context.run(async () => {
  await getResultFromDb(entryId)
});
if (result.return) {
  return;
}
```

```python Python
async def _get_result_from_db():
    return await get_result_from_db(entry_id)

result = await context.run("get-result-from-db", _get_result_from_db)

if result.should_return:
    return

```

</CodeGroup>

### Ensure Idempotency in `context.run`

Business logic should be idempotent due to potential retries in distributed systems. In other words, **when a workflow runs twice with the same input, the end result should be the same as if the workflow only ran once**.

In the example below, the `someWork` function must be idempotent:

```typescript api/workflow/route.ts
export const { POST } = serve<string>(async (context) => {
  const input = context.requestPayload

await context.run("step-1", async () => {
    return someWork(input)
  })
})
```

```python main.py
@serve.post("/api/example")
async def example(context: AsyncWorkflowContext[str]) -> None:
    input = context.request_payload

async def _step_1() -> None:
        return await some_work(input)

await context.run("step-1", _step_1)

```

</CodeGroup>

Imagine that `someWork` executes once and makes a change to a database. However, before the database had a chance to respond with the successful change, the connection is lost. Your Workflow cannot know if the database change was successful or not. The caller has no choice but to retry, which will cause `someWork` to run twice.

If `someWork` is not idempotent, this could lead to unintended consequences. For example duplicated records or corrupted data. Idempotency is crucial to maintaining the integrity and reliability of your workflow.

### Don't Nest Context Methods

Avoid calling `context.call`, `context.sleep`, `context.sleepFor`, or `context.run` within another `context.run`.

```typescript api/workflow/route.ts
import { serve } from "@upstash/workflow/nextjs"

export const { POST } = serve<string>(async (context) => {
  const input = context.requestPayload

await context.run("step-1", async () => {
    await context.sleep(...) // ❌ INCORRECT
    await context.run(...) // ❌ INCORRECT
    await context.call(...) // ❌ INCORRECT
  })
})
```

```python main.py
@serve.post("/api/example")
async def example(context: AsyncWorkflowContext[str]) -> None:
    input = context.request_payload

async def _step_1() -> None:
        await context.sleep(...) #  ❌ INCORRECT
        await context.run(...) #  ❌ INCORRECT
        await context.call(...) #  ❌ INCORRECT

await context.run("step-1", _step_1)

```

</CodeGroup>

### Include At Least One Step in Workflow

Every workflow must include at least one step execution with `context.run`. If no steps are defined, the workflow will throw a `Failed to authenticate Workflow request.` error.

```typescript ❌ Missing steps - TypeScript
export const { POST } = serve<string>(async (context) => {
  const input = context.requestPayload

// 👇 Problem: No context.run call
  console.log("Processing input:", input)

// This workflow will fail with "Failed to authenticate Workflow request."
})
```

```typescript ✅ Correct - TypeScript
export const { POST } = serve<string>(async (context) => {
  const input = context.requestPayload

// 👇 At least one step is required
  await context.run("dummy-step", async () => {
    return
  })
})
```

```python ❌ Missing steps - Python
@serve.post("/api/example")
async def example(context: AsyncWorkflowContext[str]) -> None:
    input = context.request_payload

# 👇 Problem: No context.run call
    print("Processing input:", input)

# This workflow will fail with "Failed to authenticate Workflow request."
```

```python ✅ Correct - Python
@serve.post("/api/example")
async def example(context: AsyncWorkflowContext[str]) -> None:
    input = context.request_payload

# 👇 At least one step is required
    async def _dummy_step():
        return

await context.run("dummy-step", _dummy_step)
```

</CodeGroup>

Even for the placeholder implementations, you must include one dummy step for the Workflow authentication mechanism to function properly.

### Avoid Promise.any

In workflow-js, you can use [`Promise.all` to run steps in parallel](/docs/workflow/howto/parallel-runs). However, a similar method, [`Promise.any`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise/any), is not supported for workflow steps.

While `Promise.all` works seamlessly, `Promise.any` does not currently function with workflow steps. We are exploring the possibility of adding support for `Promise.any` in the future.

If you have a specific use case that requires `Promise.any`, don't hesitate to reach out to Upstash support.

# Overview
Source: https://upstash.com/docs/workflow/basics/client

The Workflow Client lets you programmatically interact with your workflow runs.
You can use it from the same application that hosts your workflows, or from any external service.

## Initialization

Initialize a new client with your credentials:

```javascript
import { Client } from "@upstash/workflow"

const client = new Client({
  baseUrl: process.env.QSTASH_URL!,
  token: process.env.QSTASH_TOKEN!
})
```

The client is lightweight and stateless. You can safely reuse a single instance across your application.

## Functionality

The client exposes a set of functions to manage workflow runs and inspect their state:

* [client.trigger](/docs/workflow/basics/client/trigger)
* [client.cancel](/docs/workflow/basics/client/cancel)
* [client.notify](/docs/workflow/basics/client/notify)
* [client.logs](/docs/workflow/basics/client/logs)
* [client.getWaiters](/docs/workflow/basics/client/waiters)
* client.dlq
    * [client.dlq.list](/docs/workflow/basics/client/dlq/list)
    * [client.dlq.restart](/docs/workflow/basics/client/dlq/restart)
    * [client.dlq.resume](/docs/workflow/basics/client/dlq/resume)
    * [client.dlq.delete](/docs/workflow/basics/client/dlq/delete)
    * [client.dlq.retryFailureFunction](/docs/workflow/basics/client/dlq/callback)

# client.cancel
Source: https://upstash.com/docs/workflow/basics/client/cancel

Cancel one or more workflow runs. You can pass IDs directly, use filters, or cancel all at once.

## Arguments

The `cancel` method accepts one of the following:

### By ID

Pass a single workflow run ID or an array of IDs directly:

```ts
await client.cancel("<WORKFLOW_RUN_ID>");
await client.cancel(["<ID_1>", "<ID_2>"]);
```

### By filters

Pass an object with a `filter` field containing one or more filter criteria:

<ParamField body="filter" type="object">
    <Expandable defaultOpen>
        <ParamField body="workflowUrl" type="string" optional>
            Cancel workflows matching this exact URL. Cannot be combined with `workflowUrlStartingWith`.
        </ParamField>

<ParamField body="workflowUrlStartingWith" type="string" optional>
            Cancel workflows whose URL starts with this prefix. Cannot be combined with `workflowUrl`.
        </ParamField>

<ParamField body="label" type="string | string[]" optional>
            Cancel workflows with this label. Pass an array to match runs that
            have any of the given labels (OR semantics).
        </ParamField>

<ParamField body="fromDate" type="Date | number" optional>
            Cancel workflows created after this date. Accepts `Date` objects or Unix timestamps (ms).
        </ParamField>

<ParamField body="toDate" type="Date | number" optional>
            Cancel workflows created before this date. Accepts `Date` objects or Unix timestamps (ms).
        </ParamField>

<ParamField body="callerIp" type="string" optional>
            Cancel workflows triggered by this IP address.
        </ParamField>

<ParamField body="flowControlKey" type="string" optional>
            Cancel workflows with this flow control key.
        </ParamField>
    </Expandable>
</ParamField>

<ParamField body="count" type="number" optional>
    Maximum number of workflow runs to cancel per call. Defaults to `100`.
</ParamField>

### Cancel all

<ParamField body="all" type="boolean">
    Set to `true` to cancel all pending and active workflow runs.
</ParamField>

## Response

<ResponseField name="cancelled" type="number">
    The number of workflow runs that were cancelled.
</ResponseField>

## Usage

### Cancel by ID

```ts
// cancel a single workflow
await client.cancel("<WORKFLOW_RUN_ID>");

// cancel a set of workflow runs
await client.cancel(["<WORKFLOW_RUN_ID_1>", "<WORKFLOW_RUN_ID_2>"]);
```

### Cancel with URL filter

Cancel all workflow runs on a specific endpoint using a URL prefix:

```ts
await client.cancel({
  filter: { workflowUrlStartingWith: "https://your-endpoint.com" }
});
```

For an exact URL match:

```ts
await client.cancel({
  filter: { workflowUrl: "https://your-endpoint.com/api/workflow" }
});
```

### Cancel with filters

You can combine multiple filter parameters:

```ts
// cancel by label
await client.cancel({ filter: { label: "my-label" } });

// cancel by label and date range
await client.cancel({
  filter: {
    label: "my-label",
    fromDate: 1640995200000,
  }
});

// cancel by URL and date range
await client.cancel({
  filter: {
    workflowUrl: "https://your-endpoint.com/api/workflow",
    fromDate: new Date("2024-01-01"),
    toDate: new Date("2024-06-01"),
  }
});
```

### Cancel _all_ workflows

```ts
let cancelled: number;
do {
  const result = await client.cancel({ all: true });
  cancelled = result.cancelled;
} while (cancelled > 0);
```

# client.dlq.retryFailureFunction
Source: https://upstash.com/docs/workflow/basics/client/dlq/callback

If a workflow's `failureFunction` or `failureUrl` request has failed, you can retry it using the `retryFailureFunction` method:

## Arguments

## Response

## Usage
```ts
import { Client } from "@upstash/workflow";

const client = new Client({ token: "<QSTASH_TOKEN>" });

// Retry the failure callback for a specific DLQ message
const response = await client.dlq.retryFailureFunction({
  dlqId: "dlq-12345" // The ID of the DLQ message to retry
});
```

# client.dlq.delete
Source: https://upstash.com/docs/workflow/basics/client/dlq/delete

The `dlq.delete` method deletes one or more workflow runs from the **Dead Letter Queue (DLQ)**.

## Arguments

You can delete DLQ entries by ID, by an array of IDs, or by filters.

### By DLQ ID

Pass a single DLQ ID or an array of IDs directly:

```ts
await client.dlq.delete("dlq-123");
await client.dlq.delete(["dlq-123", "dlq-456"]);
```

Or as an object with `dlqIds`:

```ts
await client.dlq.delete({ dlqIds: ["dlq-123", "dlq-456"] });
```

### By filters

<ParamField body="filter" type="object">
    <Expandable defaultOpen>
        <ParamField body="workflowUrl" type="string" optional>
            Filter by exact workflow URL.
        </ParamField>

<ParamField body="workflowRunId" type="string" optional>
            Filter by workflow run ID.
        </ParamField>

<ParamField body="label" type="string | string[]" optional>
            Delete workflows with this label. Pass an array to match runs that
            have any of the given labels (OR semantics).
        </ParamField>

<ParamField body="fromDate" type="Date | number" optional>
            Delete workflows created after this date. Accepts `Date` objects or Unix timestamps (ms).
        </ParamField>

<ParamField body="toDate" type="Date | number" optional>
            Delete workflows created before this date. Accepts `Date` objects or Unix timestamps (ms).
        </ParamField>

<ParamField body="callerIp" type="string" optional>
            Filter by the IP address that triggered the workflow.
        </ParamField>

<ParamField body="flowControlKey" type="string" optional>
            Filter by flow control key.
        </ParamField>

<ParamField body="workflowCreatedAt" type="number" optional>
            Filter by workflow creation time (Unix timestamp in ms).
        </ParamField>

<ParamField body="failureFunctionState" type="string" optional>
            Filter by failure callback state.
        </ParamField>
    </Expandable>
</ParamField>

<ParamField body="count" type="number" optional>
    Maximum number of messages to process per call. Defaults to `100`.
</ParamField>

<ParamField body="cursor" type="string" optional>
    A pagination cursor from a previous request.
</ParamField>

### Delete all

<ParamField body="all" type="boolean">
    Set to `true` to delete all DLQ entries.
</ParamField>

## Response

<ResponseField name="deleted" type="number">
    The number of DLQ entries that were deleted.
</ResponseField>

<ResponseField name="cursor" type="string">
    A pagination cursor. If not returned, all matching entries have been processed.
</ResponseField>

## Usage

<CodeGroup>
```ts Single
await client.dlq.delete("dlq-123");
```
```ts Multiple
await client.dlq.delete(["dlq-123", "dlq-456"]);
```
```ts By filters
// delete by label
let cursor: string | undefined;
do {
  const result = await client.dlq.delete({
    filter: { label: "my-label" },
    cursor,
  });
  cursor = result.cursor;
} while (cursor);
```
```ts All
let cursor: string | undefined;
do {
  const result = await client.dlq.delete({ all: true, cursor });
  cursor = result.cursor;
} while (cursor);
```
</CodeGroup>

# client.dlq.list
Source: https://upstash.com/docs/workflow/basics/client/dlq/list

The `dlq.list` method retrieves messages that were sent to the **Dead Letter Queue (DLQ)**.

DLQ messages represent failed workflow or QStash deliveries that could not be retried successfully.

## Arguments

<ParamField body="cursor" type="string" optional>
    A pagination cursor from a previous request.
    Use this to fetch the next batch of results.
</ParamField>

<ParamField body="count" type="number" optional>
    Maximum number of DLQ messages to return.
    Defaults to a system-defined limit if not provided.
</ParamField>

<ParamField body="filter" type="object" optional>
    Filter options for narrowing down DLQ messages.

<Expandable defaultOpen>
        <ParamField body="workflowUrl" type="string" optional>
            Filter by exact workflow URL.
        </ParamField>

<ParamField body="workflowRunId" type="string" optional>
            Filter by workflow run ID.
        </ParamField>

<ParamField body="label" type="string | string[]" optional>
            Filter by workflow label. Pass an array to match runs that have any
            of the given labels (OR semantics).
        </ParamField>

<ParamField body="fromDate" type="Date | number" optional>
            Earliest date to include. Accepts `Date` objects or Unix timestamps (ms).
        </ParamField>

<ParamField body="toDate" type="Date | number" optional>
            Latest date to include. Accepts `Date` objects or Unix timestamps (ms).
        </ParamField>

<ParamField body="callerIp" type="string" optional>
            Filter by the IP address that triggered the workflow.
        </ParamField>

<ParamField body="flowControlKey" type="string" optional>
            Filter by flow control key.
        </ParamField>

<ParamField body="workflowCreatedAt" type="number" optional>
            Filter by workflow creation time (Unix timestamp in ms).
        </ParamField>

<ParamField body="failureFunctionState" type="string" optional>
            Filter by failure callback state.
        </ParamField>
    </Expandable>
</ParamField>

## Response

<ResponseField name="messages" type="DLQMessage[]">
    An array of DLQ messages that match the provided filters.
</ResponseField>

<ResponseField name="cursor" type="string">
    A cursor to paginate through additional results.
    If not returned, you have reached the end of the DLQ.
</ResponseField>

## Usage

```ts
import { Client } from "@upstash/workflow";

const client = new Client({ token: "<QSTASH_TOKEN>" });

// List all DLQ messages
const { messages, cursor } = await client.dlq.list();

// List with pagination and filtering
const result = await client.dlq.list({
  cursor,
  count: 10,
  filter: {
    fromDate: Date.now() - 86400000, // last 24 hours
    toDate: Date.now(),
    workflowUrl: "https://your-endpoint.com",
    label: "my-workflow",
  }
});
```

# client.dlq.restart
Source: https://upstash.com/docs/workflow/basics/client/dlq/restart

The `dlq.restart` method restarts one or more workflow runs from **Dead Letter Queue (DLQ)**.
This allows you to reprocess workflow runs that previously failed after exhausting retries.

## Arguments

The first argument specifies which DLQ entries to restart. The optional second argument provides flow control and retry settings.

### By DLQ ID

Pass a single DLQ ID or an array of IDs directly:

```ts
await client.dlq.restart("dlq-12345");
await client.dlq.restart(["dlq-12345", "dlq-67890"]);
```

### By filters

Pass an object with a `filter` field:

<ParamField body="filter" type="object">
    <Expandable defaultOpen>
        <ParamField body="workflowUrl" type="string" optional>
            Filter by exact workflow URL.
        </ParamField>

<ParamField body="workflowRunId" type="string" optional>
            Filter by workflow run ID.
        </ParamField>

<ParamField body="label" type="string | string[]" optional>
            Restart workflows with this label. Pass an array to match runs that
            have any of the given labels (OR semantics).
        </ParamField>

<ParamField body="fromDate" type="Date | number" optional>
            Restart workflows created after this date.
        </ParamField>

<ParamField body="toDate" type="Date | number" optional>
            Restart workflows created before this date.
        </ParamField>

<ParamField body="callerIp" type="string" optional>
            Filter by the IP address that triggered the workflow.
        </ParamField>

<ParamField body="flowControlKey" type="string" optional>
            Filter by flow control key.
        </ParamField>

<ParamField body="workflowCreatedAt" type="number" optional>
            Filter by workflow creation time (Unix timestamp in ms).
        </ParamField>

<ParamField body="failureFunctionState" type="string" optional>
            Filter by failure callback state.
        </ParamField>
    </Expandable>
</ParamField>

<ParamField body="count" type="number" optional>
    Maximum number of messages to process per call. Defaults to `100`.
</ParamField>

<ParamField body="cursor" type="string" optional>
    A pagination cursor from a previous request.
</ParamField>

### Restart all

<ParamField body="all" type="boolean">
    Set to `true` to restart all DLQ entries.
</ParamField>

### Options (second argument)

<ParamField body="flowControl" type="object" optional>
    An optional flow control configuration to limit concurrency and execution rate of restarted workflow runs.

See [Flow Control](/docs/workflow/features/flow-control) for details.

<Expandable title="properties">
        <ParamField body="key" type="string">
          A logical grouping key that identifies which requests share the same flow control limits.
        </ParamField>

<ParamField body="rate" type="number">
            The maximum number of allowed requests per second.
        </ParamField>

<ParamField body="parallelism" type="number">
            The maximum number of concurrent requests allowed.
        </ParamField>

<ParamField body="period" type="string|number">
            The time window used to enforce the defined rate limit. Default is `1s`.
        </ParamField>
    </Expandable>

</ParamField>

<ParamField body="retries" type="number" optional>
    Number of retry attempts to apply to the restarted workflow invocation.
    Defaults to `3` if not provided.
</ParamField>

## Response

<ResponseField name="cursor" type="string">
    A pagination cursor. If not returned, all matching entries have been processed.
</ResponseField>

<ResponseField name="workflowRuns" type="object[]">
    <Expandable defaultOpen>
        <ResponseField name="workflowRunId" type="string">
            The ID of the new workflow run created from the restarted DLQ message.
        </ResponseField>

<ResponseField name="workflowCreatedAt" type="number">
            The Unix timestamp (in milliseconds) when the new workflow run was created.
        </ResponseField>
    </Expandable>
</ResponseField>

## Usage

<CodeGroup>
```ts Single
const { messages } = await client.dlq.list();

# client.dlq.resume
Source: https://upstash.com/docs/workflow/basics/client/dlq/resume

The `dlq.resume` method resumes one or more workflow runs from the **Dead Letter Queue (DLQ)** at the point where they previously failed.
This allows you to continue execution from the failed step instead of restarting the workflow from the beginning.

## Arguments

The first argument specifies which DLQ entries to resume. The optional second argument provides flow control and retry settings.

### By DLQ ID

Pass a single DLQ ID or an array of IDs directly:

```ts
await client.dlq.resume("dlq-12345");
await client.dlq.resume(["dlq-12345", "dlq-67890"]);
```

### By filters

Pass an object with a `filter` field:

<ParamField body="filter" type="object">
    <Expandable defaultOpen>
        <ParamField body="workflowUrl" type="string" optional>
            Filter by exact workflow URL.
        </ParamField>

<ParamField body="workflowRunId" type="string" optional>
            Filter by workflow run ID.
        </ParamField>

<ParamField body="label" type="string | string[]" optional>
            Resume workflows with this label. Pass an array to match runs that
            have any of the given labels (OR semantics).
        </ParamField>

<ParamField body="fromDate" type="Date | number" optional>
            Resume workflows created after this date.
        </ParamField>

<ParamField body="toDate" type="Date | number" optional>
            Resume workflows created before this date.
        </ParamField>

<ParamField body="callerIp" type="string" optional>
            Filter by the IP address that triggered the workflow.
        </ParamField>

<ParamField body="flowControlKey" type="string" optional>
            Filter by flow control key.
        </ParamField>

<ParamField body="workflowCreatedAt" type="number" optional>
            Filter by workflow creation time (Unix timestamp in ms).
        </ParamField>

<ParamField body="failureFunctionState" type="string" optional>
            Filter by failure callback state.
        </ParamField>
    </Expandable>
</ParamField>

<ParamField body="count" type="number" optional>
    Maximum number of messages to process per call. Defaults to `100`.
</ParamField>

<ParamField body="cursor" type="string" optional>
    A pagination cursor from a previous request.
</ParamField>

### Resume all

<ParamField body="all" type="boolean">
    Set to `true` to resume all DLQ entries.
</ParamField>

### Options (second argument)

<ParamField body="flowControl" type="object" optional>
    An optional flow control configuration to limit concurrency and execution rate
    of resumed workflow runs.

See [Flow Control](/docs/workflow/features/flow-control) for details.

<Expandable title="properties">
        <ParamField body="key" type="string">
            A logical grouping key that identifies which resumed runs share the same flow control limits.
        </ParamField>

<ParamField body="rate" type="number">
            The maximum number of allowed resumption requests per second.
        </ParamField>

<ParamField body="parallelism" type="number">
            The maximum number of resumed runs that can execute concurrently.
        </ParamField>

<ParamField body="period" type="string|number">
            The time window used to enforce the defined rate limit. Default is `1s`.
        </ParamField>
    </Expandable>
</ParamField>

<ParamField body="retries" type="number" optional>
    Number of retry attempts to apply when resuming the workflow run.
    Defaults to `3` if not provided.
</ParamField>

## Response

<ResponseField name="cursor" type="string">
    A pagination cursor. If not returned, all matching entries have been processed.
</ResponseField>

<ResponseField name="workflowRuns" type="object[]">
    <Expandable defaultOpen>
        <ResponseField name="workflowRunId" type="string">
            The ID of the workflow run resumed from the DLQ message.
        </ResponseField>

<ResponseField name="workflowCreatedAt" type="number">
            The Unix timestamp (in milliseconds) when the resumed run was created.
        </ResponseField>
    </Expandable>
</ResponseField>

## Usage

<CodeGroup>
```ts Single
const { messages } = await client.dlq.list();

# client.logs
Source: https://upstash.com/docs/workflow/basics/client/logs

The `logs` method retrieves workflow run logs using the [List Workflow Runs API](/docs/workflow/api-reference/logs/list-workflow-run-logs).

## Arguments

<ParamField body="cursor" type="string" optional>
    A pagination cursor from a previous request.
    Use this to fetch the next set of results.
</ParamField>

<ParamField body="count" type="number" optional>
    Maximum number of runs to return. Defaults to a system-defined value if not specified.
</ParamField>

<ParamField body="filter" type="object" optional>
    Filter options for narrowing down workflow run logs.

<Expandable defaultOpen>
        <ParamField body="workflowRunId" type="string" optional>
            Filter by a specific workflow run ID.
        </ParamField>

<ParamField body="state" type="string" optional>
            Filter workflow runs by execution state.

| State        | Description                                |
            |--------------|--------------------------------------------|
            | `RUN_STARTED`  | The workflow run is in progress.          |
            | `RUN_SUCCESS`  | The workflow run completed successfully. |
            | `RUN_FAILED`   | The run failed after all retries.        |
            | `RUN_CANCELED` | The run was manually canceled.           |
        </ParamField>

<ParamField body="workflowUrl" type="string" optional>
            Filter by the exact workflow URL.
        </ParamField>

<ParamField body="workflowCreatedAt" type="number" optional>
            Filter by the workflow creation time (Unix timestamp).
        </ParamField>

<ParamField body="messageId" type="string" optional>
            Filter by a specific message ID.
        </ParamField>

<ParamField body="fromDate" type="Date | number" optional>
            Filter workflow runs created after this date.
        </ParamField>

<ParamField body="toDate" type="Date | number" optional>
            Filter workflow runs created before this date.
        </ParamField>

<ParamField body="callerIp" type="string" optional>
            Filter by the IP address that triggered the workflow.
        </ParamField>

<ParamField body="flowControlKey" type="string" optional>
            Filter by flow control key.
        </ParamField>
    </Expandable>
</ParamField>

## Response

<ResponseField name="cursor" type="string">
    A cursor to use for pagination.
    If no cursor is returned, there are no more workflow runs.
</ResponseField>

<ResponseField name="runs" type="Array">
  <Expandable>
    <ResponseField name="workflowRunId" type="string">
        The ID of the workflow run.
    </ResponseField>

<ResponseField name="workflowUrl" type="string">
        The URL address of the workflow endpoint.
    </ResponseField>

<ResponseField name="workflowState" type="string">
      The current state of the workflow run at this point in time

| Value          | Description                                                    |
      | -------------- | -------------------------------------------------------------- |
      | `RUN_STARTED`  | The workflow has started to run and currently in progress.     |
      | `RUN_SUCCESS`  | The workflow run has completed succesfully.                    |
      | `RUN_FAILED`   | Some errors has occured and workflow failed after all retries. |
      | `RUN_CANCELED` | The workflow run has canceled upon user request.               |

</ResponseField>

<ResponseField name="workflowCreatedAt" type="number">
      The Unix timestamp (in milliseconds) when the workflow run started.
    </ResponseField>

<ResponseField name="workflowRunCompletedAt" type="string">
        The Unix timestamp (in milliseconds) when the workflow run was completed, if applicable.
    </ResponseField>

<ResponseField name="labels" type="string[]">
    The labels of the run assigned by the user on trigger.
    </ResponseField>

<ResponseField name="label" type="string" deprecated>
    Deprecated. Use `labels` instead. When a run has multiple labels, this only
    contains the first one.
    </ResponseField>

<ResponseField name="failureFunction" type="FailureFunction">
      The details of the failure callback message, if a failure function was defined for the workflow.

<Expandable  defaultClosed>
        <ResponseField name="messageId" type="string">
          The ID of the failure callback message
        </ResponseField>

<ResponseField name="url" type="string">
          The URL address of the failure function
        </ResponseField>

<ResponseField name="state" type="string">
          The state of the failure callback

| Value                 |
          | --------------------- |
          | `CALLBACK_INPROGRESS` |
          | `CALLBACK_SUCCESS`    |
          | `CALLBACK_FAIL`       |

</ResponseField>

<ResponseField name="failHeaders" type="string">
          The HTTP headers of the message that triggered the failure function.
        </ResponseField>

<ResponseField name="failStatus" type="string">
          The HTTP response status of the message that triggered the failure function.
        </ResponseField>

<ResponseField name="failResponse" type="string">
          The response body of the message that triggered the failure function.
        </ResponseField>

<ResponseField name="dlqId" type="string">
          The DLQ ID of the workflow run.
        </ResponseField>

<ResponseField name="responseBody" type="string">
          Response body of the failure function/url.
          When [failure function](/docs/workflow/basics/serve#failurefunction) is used, this contains
          the returned message from the failure function.
        </ResponseField>

<ResponseField name="responseHeaders" type="array">
          Reponse headers of the failure function/url. This is valuable when the call to run the failure function/url is rejected
          because of a platform limit.
        </ResponseField>

<ResponseField name="responseStatus" type="int">
          Reponse status of the failure function/url. This is valuable when the call to run the failure function/url is rejected
          because of a platform limit.
        </ResponseField>

<ResponseField name="errors" type="array">
          A call to failure url/function can be retried as `maxRetries` time. This array contains errors of all retry
          attempts.

<Expandable>
            <ResponseField name="status" type="int">
              Response status of the endpoint that caused the error
            </ResponseField>

<ResponseField name="headers" type="array">
              Response Headers of the endpoint that caused the error
            </ResponseField>

<ResponseField name="body" type="string">
              Response Body of the endpoint that caused the error if available
            </ResponseField>

<ResponseField name="error" type="string">
              An error message that happened before/after calling the user's endpoint.
            </ResponseField>

<ResponseField name="time" type="int64">
                The time of the error happened in Unix time milliseconds
            </ResponseField>

</Expandable>
        </ResponseField>

<ResponseField name="maxRetries" type="string">
          Max number of retries configured when seeing an error.
        </ResponseField>
      </Expandable>
    </ResponseField>

The type of grouped steps

| Value        | Description                                                      |
          | ------------ | ---------------------------------------------------------------- |
          | `sequential` | Indicates only one step is excuted sequentially                  |
          | `parallel`   | Indicates multiple steps being executed in parallel.             |
          | `next`       | Indicates there is information about currently executing step(s) |

</ResponseField>

<ResponseField name="steps" type="Array">
          <Expandable  defaultClosed>
            <ResponseField name="stepId" type="number" >
              The ID of the step which increases monotonically.
            </ResponseField>

<ResponseField name="stepName" type="string" >
              The name of the step. It is specified in workflow by user.
            </ResponseField>

<ResponseField name="stepType" type="string" >
                Execution type of the step which indicates type of the context function.

| Value        | Function                                     |
                | ------------ | -------------------------------------------- |
                | `Initial`    | The default step which created automatically |
                | `Run`        | context.run()                                |
                | `Call`       | context.call()                               |
                | `SleepFor`   | context.sleepFor()                           |
                | `SleepUntil` | context.sleepUntil()                         |
                | `Wait`       | context.waitForEvent()                       |
                | `Notify`     | context.notify()                             |
                | `Invoke`     | context.invoke()                             |
            </ResponseField>

<ResponseField name="messageId" type="string" >
                The ID of the message associated with this step.
            </ResponseField>

<ResponseField name="out" type="string" >
                The output returned by the step
            </ResponseField>

<ResponseField name="concurrent" type="string" >
                The total number of concurrent steps that is running alongside this step
            </ResponseField>

<ResponseField name="state" type="string" >
                The state of this step at this point in time

| Value           |
                | --------------- |
                | `STEP_SUCCESS`  |
                | `STEP_RETRY`    |
                | `STEP_FAILED`   |
                | `STEP_CANCELED` |
            </ResponseField>

<ResponseField name="createdAt" type="string" >
              The unix timestamp in milliseconds when the message associated with this step has created.
            </ResponseField>

<ResponseField name="nextDeliveryTime" type="number">
              The unix timestamp in milliseconds when this step will be retried.
              This is set only when the step state is `STEP_RETRY`
            </ResponseField>

**The following fields are set only when a specific type of step is executing. These fields are not available for all step types.**

<ResponseField name="sleepFor" type="string" >
              The duration in milliseconds which step will sleep. Only set if stepType is `SleepFor`.
            </ResponseField>

<ResponseField name="sleepUntil" type="string" >
              The unix timestamp (in milliseconds) which step will sleep until. Only set if stepType is `SleepUntil`.
            </ResponseField>

<ResponseField name="waitEventId" type="string" >
              The event id of the wait step. Only set if stepType is `Wait`.
            </ResponseField>

<ResponseField name="waitTimeoutDeadline" type="string" >
              The unix timestamp (in milliseconds) when the wait will time out.
            </ResponseField>

<ResponseField name="waitTimeoutDuration" type="string">
              The duration of timeout in human readable format (e.g. 120s, 1m, 1h).
            </ResponseField>

<ResponseField name="waitTimeout" type="string" >
              Set to true if this step is cause of a wait timeout rather than notifying the waiter.
            </ResponseField>

<ResponseField name="callUrl" type="string">
                The URL of the external address. Available only if stepType is `Call`.
            </ResponseField>

<ResponseField name="callMethod" type="string">
                The HTTP method of the request sent to the external address. Available only if stepType is `Call`.
            </ResponseField>

<ResponseField name="callHeaders" type="string">
                The HTTP headers of the request sent to the external address. Available only if stepType is `Call`.
            </ResponseField>

<ResponseField name="callBody" type="string">
                The body of the request sent to the external address. Available only if stepType is `Call`.
            </ResponseField>

<ResponseField name="callResponseStatus" type="number">
                The HTTP status returned by the external call. Available only if stepType is `Call`.
            </ResponseField>

<ResponseField name="callResponseBody" type="string">
                The body returned by the external call. Available only if stepType is `Call`.
            </ResponseField>

<ResponseField name="callResponseHeaders" type="array">
                The HTTP headers returned by the external call. Available only if stepType is `Call`.
            </ResponseField>

<ResponseField name="invokedWorkflowRunId" type="string">
              The ID of the invoked workflow run if this step is an invoke step.
            </ResponseField>

<ResponseField name="invokedWorkflowUrl" type="string">
              The URL address of the workflow server of invoked workflow run if this step is an invoke step.
            </ResponseField>

<ResponseField name="invokedWorkflowCreatedAt" type="number">
              The Unix timestamp (in milliseconds) when the invoked workflow was started if this step is an invoke step.
            </ResponseField>

<ResponseField name="invokedWorkflowRunBody" type="string">
              The body passed to the invoked workflow if this step is an invoke step.
            </ResponseField>

<ResponseField name="invokedWorkflowRunHeaders" type="string">
              The HTTP headers passed to invoked workflow if this step is an invoke step.
            </ResponseField>
          </Expandable>
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

***

## Usage

```ts
import { Client } from "@upstash/workflow";

const client = new Client({ token: "<QSTASH_TOKEN>" })

const { runs, cursor } = await client.logs()
```

### Paginate with cursor

```ts
const allRuns = [];
let cursor: string | undefined;
do {
  const result = await client.logs({ cursor });
  allRuns.push(...result.runs);
  cursor = result.cursor;
} while (cursor);
```

### Filter by state

```ts
const { runs } = await client.logs({
  filter: {
    state: "RUN_FAILED",
  }
})
```

### Filter by label and date range

```ts
const { runs } = await client.logs({
  filter: {
    label: "my-workflow",
    fromDate: new Date("2024-01-01"),
    toDate: new Date("2024-06-01"),
  }
})
```

### Filter by multiple labels

Passing an array matches runs that have any of the given labels (OR semantics).
For example, with runs labelled `["label-1", "label-2"]` and `["label-2", "label-3"]`,
filtering by `["label-1", "label-2"]` returns both.

```ts
const { runs } = await client.logs({
  filter: {
    label: ["label-1", "label-2"],
  }
})
```

# client.notify
Source: https://upstash.com/docs/workflow/basics/client/notify

The `notify` method notifies workflows that are waiting for a specific event.

Workflows paused at a [`context.waitForEvent`](/docs/workflow/basics/context/waitForEvent) step with the matching `eventId` will be resumed, and the provided `eventData` will be passed back to them.

## Arguments

<ParamField body="eventId" type="string" required>
    The identifier of the event to notify.
</ParamField>

<ParamField body="eventData" type="any" optional>
    Data to deliver to the waiting workflow(s).
    This value will be returned in the `eventData` field of `context.waitForEvent`.
</ParamField>

<ParamField body="workflowRunId" type="string" optional>
    The workflow run ID to notify. When provided, enables **lookback functionality** - the notification will be stored and delivered even if `notify` is called before `waitForEvent`.

This solves race conditions where notifications might be sent before a workflow reaches its wait step.
</ParamField>

## Response

Returns a list of `Waiter` objects representing the workflows that were notified:

<ResponseField name="Waiter" type="object">
  <Expandable>
   	<ResponseField name="url" type="string" required>
      URL to call upon notify
    </ResponseField>
   	<ResponseField name="deadline" type="number" required>
      Unix timestamp for when the wait will time out
    </ResponseField>
   	<ResponseField name="headers" type="Record<string, string[]>" required>
      Headers sent in case of notify
    </ResponseField>
   	<ResponseField name="timeoutUrl" type="string">
      URL to call upon timeout
    </ResponseField>
   	<ResponseField name="timeoutBody" type="unknown">
      Body used in timeout request
    </ResponseField>
   	<ResponseField name="timeoutHeaders" type="Record<string, string[]>">
      Headers sent in case of time out
    </ResponseField>
  </Expandable>
</ResponseField>

## Usage

### Basic Notification

```javascript
import { Client } from "@upstash/workflow";

const client = new Client({ token: "<QSTASH_TOKEN>" });

await client.notify({
  eventId: "my-event-id",
  eventData: "my-data", // data passed to the workflow run
});
```

### Notification with Lookback

To prevent race conditions where a notification might arrive before the workflow reaches `waitForEvent`, you can provide a `workflowRunId`. This enables lookback - the notification will be stored and delivered even if sent before the wait step:

```javascript
import { Client } from "@upstash/workflow";

const client = new Client({ token: "<QSTASH_TOKEN>" });

// Notify a specific workflow run with lookback support
await client.notify({
  eventId: "payment-processed",
  eventData: { amount: 100, status: "success" },
  workflowRunId: "wfr_abc123", // Enables lookback for this workflow run
});
```

This is particularly useful when you know which specific workflow run should receive the notification, such as after triggering a workflow and immediately sending it an event.

# client.trigger
Source: https://upstash.com/docs/workflow/basics/client/trigger

The `trigger` method starts a new workflow run and returns its `workflowRunId`.

You can also trigger multiple workflow runs in a single call by passing an array of arguments instead of a single object.

## Arguments

<ParamField body="url" type="string" required>
    The public URL of the workflow endpoint.
</ParamField>

<ParamField body="workflowRunId" type="string" optional>
    A custom identifier for the workflow run.
    Each run must use a unique ID.

The final ID will be prefixed with `wfr_`.
    For example: passing `my-workflow` results in `wfr_my-workflow`.

If omitted, a run ID will be generated automatically.
</ParamField>

<ParamField body="body" type="string | object" optional>
    The request payload to pass into the workflow run.
    Accessible as `context.requestPayload` inside the workflow.
</ParamField>

<ParamField body="headers" type="object" optional>
    HTTP headers to pass into the workflow run.
    Accessible as `context.headers` inside the workflow.
</ParamField>

<ParamField body="retries" type="string">
    Number of retry attempts for workflow steps. Default is 3.
</ParamField>

<ParamField body="retryDelay" type="string">
    Delay between retries. Can use expressions like "1000 * (1 + retried)".
</ParamField>

<ParamField body="flowControl" type="object" optional>
    An optional flow control configuration to limit concurrency and execution rate of the workflow runs.

See [Flow Control](/docs/workflow/features/flow-control) for details.

<Expandable title="properties">
        <ParamField body="key" type="string">
          A logical grouping key that identifies which requests share the same flow control limits.
        </ParamField>

<ParamField body="rate" type="number">
            The maximum number of allowed requests per second.
        </ParamField>

<ParamField body="parallelism" type="number">
            The maximum number of concurrent requests allowed.
        </ParamField>

<ParamField body="period" type="string|number">
            The time window used to enforce the defined rate limit. Default is `1s`.
        </ParamField>
    </Expandable>
</ParamField>

<ParamField body="delay" type="string">
    Delay for the workflow run. This is used to delay the execution of the workflow run. The delay is in seconds or can be passed as a string with a time unit (e.g. "1h", "30m", "15s").
</ParamField>

<ParamField body="notBefore" type="number">
  Optionally set the absolute delay of this message.
  This will override the delay option.
  The message will not delivered until the specified time.

Unix timestamp in seconds.
</ParamField>

<ParamField body="label" type="string | string[]">
  An optional label to assign to the workflow run.
  This can be useful for identifying and filtering runs in the dashboard or logs.

Pass an array to attach multiple labels to a single workflow run. The run will
  then match a [logs](/docs/workflow/basics/client/logs) or DLQ filter for any of its
  labels (OR semantics).
</ParamField>

<ParamField body="disableTelemetry" type="boolean">
  If set to true, telemetry data collection for this workflow run will be disabled.
  By default, telemetry is enabled to help improve Upstash services.

See the [`disableTelemetry` parameter in serve options](/docs/workflow/basics/serve/advanced#param-disable-telemetry) for more details.
</ParamField>

## Usage
<CodeGroup>
```ts Single Workflow
import { Client } from "@upstash/workflow";

const client = new Client({ token: "<QSTASH_TOKEN>" })

const { workflowRunId } = await client.trigger({
  url: "https://<YOUR_WORKFLOW_ENDPOINT>/<YOUR-WORKFLOW-ROUTE>",
  body: "hello there!",         // optional body
  headers: { ... },             // optional headers
  workflowRunId: "my-workflow", // optional workflow run id
  retries: 3,                   // optional retries
  retryDelay: "1000 * (1 + retried)", // optional delay between retries
  delay: "10s"                  // optional delay value
  failureUrl: "https://<YOUR_FAILURE_URL>", // optional failure url
  flowControl: {                // optional flow control
    key: "USER_GIVEN_KEY",
    rate: 10,
    parallelism: 5,
    period: "10m"
  },
})
```

```ts Multiple Workflows
import { Client } from "@upstash/workflow";

const client = new Client({ token: "<QSTASH_TOKEN>" })
const results = await client.trigger([
  {
    url: "<YOUR_WORKFLOW_ENDPOINT>",
    // other options...
  },
  {
    url: "<YOUR_WORKFLOW_ENDPOINT>",
    // other options...
  },
])

console.log(results[0].workflowRunId)
// prints wfr_my-workflow
```
</CodeGroup>

# client.getWaiters
Source: https://upstash.com/docs/workflow/basics/client/waiters

The `getWaiters` method retrieves all waiters that are currently listening for a given event.

A **waiter** represents a workflow run that is paused at a `context.waitForEvent` step and is waiting for the specified `eventId`.

## Arguments

<ParamField body="eventId" type="string" required>
    The identifier of the event to look up.
</ParamField>

## Response

Returns a list of `Waiter` objects describing workflows that are waiting on the given event.

## Usage

```javascript
import { Client } from "@upstash/workflow";

const client = new Client({ token: "<QSTASH_TOKEN>" });

const result = await client.getWaiters({
  eventId: "my-event-id",
});
```

# Overview
Source: https://upstash.com/docs/workflow/basics/context

A workflow's **context** is an object provided by the route function.

The context object provides:
* **Workflow APIs** – functions for defining workflow steps.
* **Workflow Run Properties** – request payload, request headers, and other metadata.

<CodeGroup>
    ```typescript api/workflow/route.ts highlight={4-5}
    import { serve } from "@upstash/workflow/nextjs";

export const { POST } = serve(
      // 👇 the workflow context
      async (context) => {
        // ...
      }
    );
    ```

```python main.py
    from fastapi import FastAPI
    from upstash_workflow.fastapi import Serve
    from upstash_workflow import AsyncWorkflowContext

app = FastAPI()
    serve = Serve(app)

@serve.post("/api/example")
    async def example(context: AsyncWorkflowContext[str]) -> None: ...

```
</CodeGroup>

## Context Object Properties

<ParamField path="requestPayload" type="object">
  The request payload passed to the workflow run via `trigger()` call.
</ParamField>

<ParamField path="headers" type="object">
  The request headers passed to the workflow run via `trigger()` call.
</ParamField>

<ParamField path="workflowRunId" type="string">
  The unique identifier of the current workflow run.
</ParamField>

<ParamField path="url" type="string">
  The public URL of the workflow endpoint.
</ParamField>

<ParamField path="failureUrl" type="string">
  The URL used for workflow failure callback.

If a failure function is defined, this is the same as the workflow's `url`.
</ParamField>

<ParamField path="env" type="object">
  The environment variables available to the workflow.
</ParamField>

<ParamField path="qstashClient" type="object">
  The QStash client instance used by the workflow endpoint.
</ParamField>

<ParamField path="labels" type="string[]">
  The labels attached to the current workflow run, if set in [client.trigger](/docs/workflow/basics/client/trigger).
  Defaults to an empty array when no label was set.
</ParamField>

<ParamField path="label" type="string | undefined" deprecated>
  Deprecated. Use `labels` instead. When a run has multiple labels, this only
  returns the first one.
</ParamField>

## Context Object Functions

You can use the functions exposed by context object to define workflow steps.

* [context.run](/docs/workflow/basics/context/run)
* [context.sleep](/docs/workflow/basics/context/sleep)
* [context.sleepUntil](/docs/workflow/basics/context/sleepUntil)
* [context.waitForEvent](/docs/workflow/basics/context/waitForEvent)
* [context.createWebhook](/docs/workflow/basics/context/createWebhook)
* [context.waitForWebhook](/docs/workflow/basics/context/waitForWebhook)
* [context.notify](/docs/workflow/basics/context/notify)
* [context.invoke](/docs/workflow/basics/context/invoke)
* [context.call](/docs/workflow/basics/context/call)
* [context.cancel](/docs/workflow/basics/context/cancel)
* [context.api](/docs/workflow/basics/context/api)

# context.api
Source: https://upstash.com/docs/workflow/basics/context/api

In addition to `context.call`, you can also make third‑party requests using the `context.api` namespace.

This namespace provides built‑in integrations for **OpenAI**, **Anthropic**, and **Resend**, allowing you to make requests in a **type‑safe** manner.

```typescript OpenAI
const { status, body } = await context.api.openai.call("Call OpenAI", {
  token: "<OPENAI_API_KEY>",
  operation: "chat.completions.create",
  body: {
    model: "gpt-4o",
    messages: [
      {
        role: "system",
        content: "Assistant says 'hello!'",
      },
      { role: "user", content: "User shouts back 'hi!'" },
    ],
  },
});
```

```typescript Anthropic
const { status, body } = await context.api.anthropic.call(
  "Call Anthropic",
  {
    token: "<ANTHROPIC_API_KEY>",
    operation: "messages.create",
    body: {
      model: "claude-3-5-sonnet-20241022",
      max_tokens: 1024,
      messages: [
          {"role": "user", "content": "Hello, world"}
      ]
    },
  }
);
```

```typescript Resend
const { status, body } = await context.api.resend.call("Call Resend", {
  token: "<RESEND_API_KEY>",
  body: {
    from: "Acme <onboarding@resend.dev>",
    to: ["delivered@resend.dev"],
    subject: "Hello World",
    html: "<p>It works!</p>",
  },
  headers: {
    "content-type": "application/json",
  },
});
```

</CodeGroup>

We'll continue adding more integrations over time. If you'd like to see a specific integration, feel free to contribute to the SDK or contact us with your suggestion.

For detailed guides on usage and configuration, see the [Integrations section](/docs/workflow/integrations/openai).

# context.call
Source: https://upstash.com/docs/workflow/basics/context/call

`context.call()` performs an HTTP request as a workflow step, supporting longer response times up to 12 hours.

The request is executed by **Upstash on your behalf**, so your application does not consume compute resources during the request duration.

If the endpoint responds with a non‑success status code (anything outside `200–299`),
`context.call()` still returns the response and the workflow continues.
This allows you to inspect the response (via the `status` field) and decide how to handle failure cases in your logic.

If you want requests to retry automatically, you can explicitly pass a retry configuration.

## Arguments

<ParamField body="url" type="string">
    The URL of the HTTP endpoint to call.
</ParamField>

<ParamField body="method" type="string">
    TThe HTTP method to use (`GET`, `POST`, `PUT`, etc.). Defaults to `GET`.
</ParamField>

<ParamField body="body" type="string">
    The request body as a string.
</ParamField>

<ParamField body="headers" type="object">
   A map of headers to include in the request.
</ParamField>

<ParamField body="retries" >
    Number of retry attempts if the request fails. Defaults to `0` (no retries).
</ParamField>

<ParamField body="retryDelay" >
    Delay between retries (in milliseconds). By default, uses exponential backoff. You can use mathematical expressions and the special variable `retried` (current retry attempt count starting from 0). Examples: `1000`, `pow(2, retried)`, `max(10, pow(2, retried))`.
</ParamField>

<ParamField body="flowControl" type="object" optional>
    Throttle outbound requests.

See [Flow Control](/docs/workflow/features/flow-control) for details.

<Expandable title="properties">
        <ParamField body="key" type="string">
          A logical grouping key that identifies which requests share the same flow control limits.
        </ParamField>

<ParamField body="rate" type="number">
            The maximum number of allowed requests per second.
        </ParamField>

<ParamField body="parallelism" type="number">
            The maximum number of concurrent requests allowed.
        </ParamField>

<ParamField body="period" type="string|number">
            The time window used to enforce the defined rate limit. Default is `1s`.
        </ParamField>
    </Expandable>
</ParamField>

<ParamField body="timeout" type="number" >
    Maximum time (in seconds) to wait for a response.
    If retries are enabled, this timeout applies individually to each attempt.
</ParamField>

<ParamField body="workflow" >
    When using [`serveMany`](/docs/workflow/features/invoke/serveMany#using-serve-manyny), you can call another workflow defined in the same `serveMany` by passing it to this parameter.
</ParamField>

## Response

<ResponseField name="status" type="number">
    The HTTP response status code.
</ResponseField>

<ResponseField name="body" type="string">
    The response body.

`context.call()` attempts to parse the body as JSON.
    If parsing fails, the raw body string is returned.
</ResponseField>

<ResponseField name="headers" type="dictionary">
    The response headers.
</ResponseField>

<Tip>
    In TypeScript, you can declare the expected result type for strong typing:

```typescript
    type ResultType = {
      field1: string,
      field2: number
    };

const result = await context.call<ResultType>( ... );
    ```
</Tip>

## Usage

```javascript TypeScript
import { serve } from "@upstash/workflow/nextjs";

export const { POST } = serve<{ topic: string }>(async (context) => {
  const { userId, name } = context.requestPayload;

const { status,  headers,  body } = await context.call("sync-user-data", {
      url: "https://my-third-party-app", // Endpoint URL
      method: "POST",
      body: JSON.stringify({
        userId,
        name
      }),
      headers: {
        authorization: `Bearer ${process.env.OPENAI_API_KEY}`,
      },
    }
  );
});

```

```python Python
from fastapi import FastAPI
from upstash_workflow.fastapi import Serve
from upstash_workflow import AsyncWorkflowContext

app = FastAPI()
serve = Serve(app)

@dataclass
class Request:
    topic: str

@serve.post("/api/example")
async def example(context: AsyncWorkflowContext[Request]) -> None:
    request: Request = context.request_payload

result = await context.call(
        "generate-long-essay",
        url="https://api.openai.com/v1/chat/completions",
        method="POST",
        body={
            "model": "gpt-4o",
            "messages": [
                {
                    "role": "system",
                    "content": "You are a helpful assistant writing really long essays that would cause a normal serverless function to timeout.",
                },
                {"role": "user", "content": request["topic"]},
            ],
        },
        headers={
            "authorization": f"Bearer {os.environ['OPENAI_API_KEY']}",
        },
    )

status, headers, body = result.status, result.headers, result.body

```

</CodeGroup>

<Tip>
    We provide integrations for **OpenAI, Anthropic, and Resend**, allowing you to call their APIs with strongly typed request bodies using `context.call`.
    See [`context.api`](/docs/workflow/basics/context#context-api) for details.
</Tip>

<Info>
  The `context.call()` function can make requests to any public API endpoint. However, it cannot:

* Make requests to localhost (unless you set up a local tunnel, [here's how](http://localhost:3000/workflow/howto/local-development))
  * Make requests to internal Upstash QStash endpoints.
</Info>

# context.cancel
Source: https://upstash.com/docs/workflow/basics/context/cancel

All of the methods covered so far are used to define workflow steps.

`context.cancel` is different — it allows you to **explicitly cancel the current workflow run**.

```ts
export const { POST } = serve<{ topic: string }>(async (context) => {
  const payload = context.requestPayload

const result = await context.run("check if canceled", () => { ... });

if (result.cancel) {
    await context.cancel() // cancel the workflow run
  }
})
```

When a workflow run is canceled:

* It is labeled as **canceled** (not failed).
* The configured `failureFunction` **is not triggered**.
* No entries are sent to the **dead-letter queue (DLQ)**.

# context.createWebhook
Source: https://upstash.com/docs/workflow/basics/context/createWebhook

`context.createWebhook()` creates a unique webhook that can be called by external services to trigger workflow continuation.

The webhook URL generated can be called multiple times to resume multiple [`context.waitForWebhook`](/docs/workflow/basics/context/waitForWebhook) steps.

## Arguments

## Response

<ResponseField name="webhookUrl" type="string">
    The unique webhook URL that external services should call to resume the workflow.

Can be called multiple times to resume multiple [`context.waitForWebhook`](/docs/workflow/basics/context/waitForWebhook) steps.
</ResponseField>

<ResponseField name="eventId" type="string">
    The internal event identifier associated with this webhook.
    This is primarily used internally by [`context.waitForWebhook`](/docs/workflow/basics/context/waitForWebhook).
</ResponseField>

## Usage

```typescript highlight={4}
import { serve } from "@upstash/workflow/nextjs";

export const { POST } = serve(async (context) => {
  const webhook = await context.createWebhook("create webhook");

console.log(webhook.webhookUrl); // Use this URL with external services
});
```

For more complete examples and use cases, see [the page on webhooks](/docs/workflow/features/webhooks).

# context.invoke
Source: https://upstash.com/docs/workflow/basics/context/invoke

`context.invoke()` triggers another workflow run and pauses until the invoked workflow finishes.

The calling workflow resumes once the invoked workflow either **succeeds**, **fails**, or is **canceled**.

<Note>
    Workflows can only invoke other workflows that were served together in the same `serveMany` route.
    For details, see [Invoke other workflows](/docs/workflow/features/invoke).
</Note>

## Arguments

<ParamField body="workflow" type="function" required>
    The workflow definition to invoke.
    Must be a workflow exposed under the same `serveMany`.
</ParamField>

<ParamField body="body" type="any">
    The payload to send to the invoked workflow.
    This value will be set as `context.requestPayload` in the invoked workflow.
</ParamField>

<ParamField body="headers" type="object" optional>
    Optional HTTP headers to forward to the invoked workflow.
    This value will be set as `context.headers` in the invoked workflow.
</ParamField>

<ParamField body="workflowRunId" type="string" optional>
    Override the workflow run ID for the invoked workflow.
    Defaults to a new ID if not specified.
</ParamField>

<ParamField body="retries" type="number" optional>
    Number of retry attempts configuration of the invoked workflow.
    Defaults to `3`. Retries use exponential backoff.
</ParamField>

<ParamField body="retryDelay" type="number|string" optional>
    Delay between retries of the invoked workflow.
</ParamField>

<ParamField body="flowControl" type="object" optional>
    Flow control configuration of the invoked workflow.

See [Flow Control](/docs/workflow/features/flow-control) for details.

<Expandable title="properties">
        <ParamField body="key" type="string">
          A logical grouping key that identifies which requests share the same flow control limits.
        </ParamField>

<ParamField body="rate" type="number">
            The maximum number of allowed requests per second.
        </ParamField>

<ParamField body="parallelism" type="number">
            The maximum number of concurrent requests allowed.
        </ParamField>

<ParamField body="period" type="string|number">
            The time window used to enforce the defined rate limit. Default is `1s`.
        </ParamField>
    </Expandable>
</ParamField>

## Response

<ResponseField name="body" type="any">
    The response body returned by the invoked workflow.
</ResponseField>

<ResponseField name="isFailed" type="boolean">
    `true` if the invoked workflow completed with failure.
</ResponseField>

<ResponseField name="isCanceled" type="boolean">
    `true` if the invoked workflow was canceled before completion.
</ResponseField>

## Usage

```ts
const { body, isFailed, isCanceled } = await context.invoke(
  "invoke another workflow",
  {
    workflow: anotherWorkflow,
    body: "test",
    header: {...}, // headers to pass to anotherWorkflow (optional)
    retries,       // number of retries (optional, default: 3)
    retryDelay,    // delay between retries (optional, uses exponential backoff by default)
    flowControl,   // flow control settings (optional)
    workflowRunId  // workflowRunId to set (optional)
  }
);
```

# context.notify
Source: https://upstash.com/docs/workflow/basics/context/notify

`context.notify()` notifies workflows that are waiting for a specific event, passing along an optional payload.

It is typically used in combination with [`context.waitForEvent`](/docs/workflow/basics/context#context-waitforevent).

## Arguments

<ParamField body="stepName" type="string">
    A unique identifier for the step.
</ParamField>

<ParamField body="eventId" type="string">
    The identifier of the event to notify.
    Must match the `eventId` used in `context.waitForEvent`.
</ParamField>

<ParamField body="eventData" type="any">
    Data to deliver to the waiting workflow(s).
    This value will be returned in `eventData` from the corresponding `waitForEvent` call.
</ParamField>

This solves race conditions where notifications might be sent before a workflow reaches its wait step.
</ParamField>

## Response

`context.notify()` returns a list of waiters describing the workflows that were notified.

<ResponseField name="notifyResponse" type="NotifyResponse[]">
    A list of `NotifyResponse` objects describing each workflow that was waiting on the event.

<Expandable defaultOpen>
        <ResponseField name="messageId" type="string">
            The ID of the notification message delivered to the workflow.
            This is unique to every notification.
        </ResponseField>

<ResponseField name="workflowRunId" type="string">
            The unique identifier of the workflow run that was notified.
        </ResponseField>

<ResponseField name="workflowCreatedAt" type="number">
            Unix timestamp (in milliseconds) representing when the workflow was created.
        </ResponseField>

</ResponseField>

## Usage

### Basic Notification

```javascript
import { serve } from "@upstash/workflow/nextjs";

export const { POST } = serve<{ topic: string }>(async (context) => {
  const payload = context.requestPayload;

const {
    notifyResponse, // result of notify, which is a list of notified waiters
  } = await context.notify("notify step", "my-event-Id", payload);
});
```

### Notification with Lookback

To prevent race conditions, you can provide a `workflowRunId`. This enables lookback - the notification will be stored and delivered even if sent before the target workflow reaches `waitForEvent`:

```javascript
import { serve } from "@upstash/workflow/nextjs";

export const { POST } = serve<{ orderId: string }>(async (context) => {
  const { orderId } = context.requestPayload;

// Process payment
  await context.run("process-payment", async () => {
    return processPayment(orderId);
  });

// Notify a specific workflow run with lookback support
  const {
    notifyResponse,
  } = await context.notify(
    "notify payment complete",
    "payment-processed",
    { orderId, status: "success" },
    "wfr_order_processor_123" // Enables lookback for this workflow run
  );
});
```

# context.run
Source: https://upstash.com/docs/workflow/basics/context/run

`context.run()` executes a piece of custom business logic as a workflow step.

It returns a `Promise`, so you can decide how steps execute:
* **Sequentially** by awaiting them one by one.
* **In parallel** by awaiting multiple steps together.

##  Arguments

<ParamField body="stepName" type="string">
    A unique identifier for the step.
</ParamField>

<ParamField body="stepFunction" type="function">
    The business logic to run inside this step.
</ParamField>

## Response

Each step can return a JSON-serializable value—anything from simple primitives to complex objects.

The value is **JSON-serialized** and automatically restored across requests.

<Warning>
    Avoid returning stateful resources such as database connections or file handles.

Instead, return plain data (numbers, strings, arrays, objects) so the result can be safely persisted and restored across workflow executions.
</Warning>

## Usage

<CodeGroup>
    ```typescript Serial execution (TypeScript) highlight={6-8, 10-12}
    import { serve } from "@upstash/workflow/nextjs";

export const { POST } = serve<string>(async (context) => {
      const input = context.requestPayload;

const result1 = await context.run("step-1", async () => {
        return someWork(input);
      });

await context.run("step-2", async () => {
        someOtherWork(result1);
      });
    });

```

```typescript Parallel execution (TypeScript)
    import { serve } from "@upstash/workflow/nextjs"

export const { POST } = serve<string>(
      async (context) => {
        const input = context.requestPayload;

const promise1 = context.run("step-1", async () => {
          return someWork(input);
        });

const promise2 = context.run("step-2", async () => {
          return someOtherWork(input);
        });

await Promise.all([promise1, promise2]);
      },
    );
    ```

```python Serial execution (Python)
    from fastapi import FastAPI
    from upstash_workflow.fastapi import Serve
    from upstash_workflow import AsyncWorkflowContext

app = FastAPI()
    serve = Serve(app)

@serve.post("/api/example")
    async def example(context: AsyncWorkflowContext[str]) -> None:
        input = context.request_payload

async def _step1():
            return some_work(input)

result1 = await context.run("step-1", _step1)

async def _step2():
            return some_other_work(result1)

await context.run("step-2", _step2)

```
</CodeGroup>

<Info>
    Because results are JSON-serialized, **class instances are restored as plain objects**.
    This means instance methods will not be available unless you explicitly rehydrate the object.

To fix this, you can recreate the instance using Object.assign() or a custom factory:
    ```typescript
   export const { POST } = serve(
    async (context) => {

let user = await context.run("step-1", async () => {
         // 👇 Return a class instance from step
         return new User("John Doe", "john.doe@example.com");
       });

// 👇 Properties are accessible by default
       console.log(user.name)

// 👇 Create a Proper Instance with Object.assign()
       user = Object.assign(new User(), user);

await context.run("greet", async () => {
         // 👇 Now instance methods are available as well
         console.log(user.greet());
       });
     }
   );
    ```
</Info>

# context.sleep
Source: https://upstash.com/docs/workflow/basics/context/sleep

`context.sleep()` pauses workflow execution for a specified duration.

When a workflow is paused, the current request completes and a new one is automatically scheduled to resume after the delay.
This ensures no compute resources are consumed during the sleep period.

<Note>Always `await` a `sleep` step to properly pause execution.</Note>

##  Arguments

<ParamField body="stepName" type="string">
    A unique identifier for the step.
</ParamField>

<ParamField body="duration" type="number|string">
    The duration to pause workflow execution.

* **Human-readable string format:**

| Input   | Duration    |
    |---------|-------------|
    | `"10s"` | 10 seconds  |
    | `"1m"`  | 1 minute    |
    | `"30m"` | 30 minutes  |
    | `"2h"`  | 2 hours     |
    | `"1d"`  | 1 day       |
    | `"1w"`  | 1 week      |
    | `"1mo"` | 1 month     |
    | `"1y"`  | 1 year      |

* **Numeric format (seconds):**

| Input   | Duration      |
    |---------|---------------|
    | `60`    | 60 seconds (1 minute) |
    | `3600`  | 3600 seconds (1 hour) |
    | `86400` | 86400 seconds (1 day) |
</ParamField>

## Usage

```typescript TypeScript highlight={12-13}
import { serve } from "@upstash/workflow/nextjs";
import { signIn, sendEmail } from "@/utils/onboarding-utils";

export const { POST } = serve<User>(async (context) => {
  const userData = context.requestPayload;

const user = await context.run("sign-in", async () => {
    const signedInUser = await signIn(userData);
    return signedInUser;
  });

// 👇 Wait for one day (in seconds)
  await context.sleep("wait-until-welcome-email", "1d");

await context.run("send-welcome-email", async () => {
    return sendEmail(user.name, user.email);
  });
});
```

```python Python
from fastapi import FastAPI
from upstash_workflow.fastapi import Serve
from upstash_workflow import AsyncWorkflowContext
from onboarding_utils import sign_in, send_email

app = FastAPI()
serve = Serve(app)

@serve.post("/api/onboarding")
async def onboarding(context: AsyncWorkflowContext[User]) -> None:
    user_data = context.request_payload

async def _sign_in():
        return await sign_in(user_data)

user = await context.run("sign-in", _sign_in)

# 👇 Wait for one day (in seconds)
    await context.sleep("wait-until-welcome-email", "1d")

async def _send_email():
        return await send_email(user.name, user.email)

await context.run("send-welcome-email", _send_email)

```

</CodeGroup>

# context.sleepUntil
Source: https://upstash.com/docs/workflow/basics/context/sleepUntil

`context.sleepUntil()` pauses workflow execution until a specific timestamp.

When a workflow is paused, the current request completes and a new one is automatically scheduled to resume at the target time.
This ensures no compute resources are consumed while sleeping.

<Note>Always await a `sleepUntil` step to properly pause execution.</Note>

##  Arguments

<ParamField body="stepName" type="string">
    A unique identifier for the step.
</ParamField>

<ParamField body="datetime" type="Date|number|string">
    The target time when the workflow should resume.
    Accepted formats:
    * A **number**: Unix timestamp in seconds
    * A **Date object**
    * A **string** that can be parsed by `new Date(string)` in JavaScript
</ParamField>

## Usage

```typescript TypeScript highlight={11-16}
import { serve } from "@upstash/workflow/nextjs";
import { signIn, sendEmail } from "@/utils/onboarding-utils";

export const { POST } = serve<User>(async (context) => {
  const userData = context.requestPayload;

const user = await context.run("sign-in", async () => {
    return signIn(userData);
  });

// 👇 Calculate the date for one week from now
  const oneWeekFromNow = new Date();
  oneWeekFromNow.setDate(oneWeekFromNow.getDate() + 7);

// 👇 Sleep until the calculated date
  await context.sleepUntil("wait-for-one-week", oneWeekFromNow);

await context.run("send-welcome-email", async () => {
    return sendEmail(user.name, user.email);
  });
});
```

```python Python
from fastapi import FastAPI
from datetime import datetime, timedelta
from upstash_workflow.fastapi import Serve
from upstash_workflow import AsyncWorkflowContext
from onboarding_utils import sign_in, send_email

app = FastAPI()
serve = Serve(app)

@serve.post("/api/onboarding")
async def onboarding(context: AsyncWorkflowContext[User]) -> None:
    user_data = context.request_payload

async def _sign_in():
        return await sign_in(user_data)

user = await context.run("sign-in", _sign_in)

# 👇 Calculate the date for one week from now
    one_week_from_now = datetime.now() + timedelta(days=7)

# 👇 Wait until the calculated date
    await context.sleep_until("wait-for-one-week", one_week_from_now)

async def _send_email():
        return await send_email(user.name, user.email)

await context.run("send-welcome-email", _send_email)

```

</CodeGroup>

# context.waitForEvent
Source: https://upstash.com/docs/workflow/basics/context/waitForEvent

`context.waitForEvent` pauses workflow execution until a given event occurs or a timeout is reached.

Default timeout value is 7 days.

## Arguments

<ParamField body="stepId" type="string" required>
    A unique identifier for the step.
</ParamField>

<ParamField body="eventId" type="string" required>
    A unique identifier for the event to wait on.
</ParamField>

<ParamField body="timeout" type="number|string">
    The maximum time to wait before continuing execution.

* **String format**: Human‑readable duration (e.g., `"10s"`, `"2h"`, `"1d"`).
    * **Number format**: Duration in seconds (e.g., `60`, `3600`).

Defaults to `7d` (7 days).
</ParamField>

## Response

<ResponseField name="eventData" type="string|object">
    The data passed in when the event is triggered via `notify()`.
</ResponseField>

<ResponseField name="timeout" type="boolean">
    `true` if execution resumed because the timeout elapsed,
    `false` if resumed due to the event being received.
</ResponseField>

## Usage

```javascript highlight={6-11}
import { serve } from "@upstash/workflow/nextjs";

export const { POST } = serve<{ topic: string }>(async (context) => {
  const request = context.requestPayload;

const {
    eventData,
    timeout,
  } = await context.waitForEvent("wait for some event", "my-event-id", {
    timeout: "1000s", // 1000 second timeout
  });
});

```

# context.waitForWebhook
Source: https://upstash.com/docs/workflow/basics/context/waitForWebhook

`context.waitForWebhook()` pauses workflow execution until the webhook created by `createWebhook` is called or a timeout is reached.

You can call `context.waitForWebhook` with the same `webhook` object multiple times to wait for multiple calls to the same webhook URL.

## Arguments

<ParamField body="webhook" type="object" required>
    The webhook object returned by `context.createWebhook()`.

<Expandable title="properties">
        <ParamField body="webhookUrl" type="string">
            The webhook URL to wait for.
        </ParamField>

<ParamField body="eventId" type="string">
            The internal event identifier.
        </ParamField>
    </Expandable>
</ParamField>

<ParamField body="timeout" type="string" required>
    The maximum time to wait before continuing execution.

Should be passed in Human‑readable duration (e.g., `"10s"`, `"2h"`, `"1d"`).
</ParamField>

## Response

The response varies depending on whether the webhook was called before the timeout:

<ResponseField name="timeout" type="boolean">
    * `false` if the webhook was called successfully
    * `true` if execution resumed because the timeout elapsed
</ResponseField>

<ResponseField name="request" type="Request | undefined">
    The HTTP request object received by the webhook (only present when `timeout` is `false`).

Contains the full request details including method, headers, body, and URL.
</ResponseField>

## Usage

### Basic Example

```typescript highlight={8-13}
import { serve } from "@upstash/workflow/nextjs";

export const { POST } = serve(async (context) => {
  // Create webhook
  const webhook = await context.createWebhook("create webhook");

// Wait for webhook to be called with 30 second timeout
  const webhookResponse = await context.waitForWebhook(
    "wait for webhook",
    webhook,
    "30s"
  );

if (webhookResponse.timeout) {
    console.log("Webhook was not called within the timeout period");
  } else {
    console.log("Webhook was called successfully");
    console.log("Request body:", webhookResponse.request.body);
    console.log("Request headers:", webhookResponse.request.headers);
  }
});
```

For more complete examples and use cases, see [the page on webhooks](/docs/workflow/features/webhooks).

# How Workflow Works
Source: https://upstash.com/docs/workflow/basics/how

Upstash Workflow is an orchestration layer that allows you to write **multi‑step workflows** which are:

* **Durable** – steps automatically recover from errors or outages
* **Scalable** – steps run independently and in parallel when possible
* **Cost‑efficient** – idle waiting (delays, sleeps, external calls) does not consume compute resources

Upstash Workflow is built on top of Upstash QStash, our serverless messaging and scheduling solution, to achieve these features.

## The Core Idea

Traditionally, backend functions are built in one of two ways: either everything is executed inside a single API function—which is difficult to maintain and prone to failures—or the flow is split across multiple APIs connected by a queueing system, which adds significant infrastructure and state‑management overhead.

These approaches can work, but they often fail to handle production load reliably or become increasingly difficult to maintain over time:

* **Timeouts** – the whole function runs inside one execution window. A slow API can easily exceed serverless limits (often 10–60 seconds).
* **Temporary issues** – slow or unreliable external services can exceed serverless limits or cause the entire request to fail.
* **Failures** – if a step fails, the whole request fails. You either restart everything or you must write custom retry logic.
* **Rate limits** – calling external APIs in bulk requires careful concurrency control, which is difficult to implement manually.
* **Complexity** – to address these issues, teams often build custom queues, schedulers, or state trackers, adding unnecessary infrastructure overhead.

***

## How Upstash Workflow Solves This

Upstash Workflow takes a different approach:
instead of treating your entire function as one continuous execution, **it splits your logic into multiple steps in a workflow endpoint**, each managed and retried by the orchestration engine.

* Each step is executed in its own **HTTP call** to your application.
* After a step finishes, its result is **stored in durable state** inside Upstash Workflow.
* On the next execution, Workflow **skips completed steps** and **resumes exactly where it left off by restoring the previous step results**.
* If a step fails, it is retried automatically based on your retry configuration.

This means you no longer need custom queues, retry logic, or manual state management. You just define your workflow once, and the orchestration layer ensures that **every step runs once, in order, with full reliability.**

<img />

***

## Extended Features

Upstash Workflow extends the basic step model with additional primitives:

* **Parallel Steps**
  Define multiple steps (e.g. inside a `Promise.all()`). The engine detects independent work and runs steps concurrently as separate HTTP executions.

* **Delays / Sleep**
  `context.sleep` and `context.sleepUntil` allow pausing a workflow for hours, days, or even months. No compute is held during the wait time; execution resumes when the delay has expired.

* **External Event Handling**
  `context.waitForEvent` pauses execution until you notify the workflow externally (e.g. via webhook or user action). State is persisted until the event arrives.

* **External Calls**
  Use `context.call` to have Upstash perform slow or unreliable HTTP calls. Instead of blocking your function, the call is handled by Upstash. When it completes, the workflow resumes with the response.

***

This architecture makes your serverless functions durable, reliable, and performance‑optimized, even in the face of runtime errors or temporary service outages.

It's quick and easy to get started: follow the [Quickstarts](/docs/workflow/quickstarts/platforms) to define your first workflow in minutes.

# Overview
Source: https://upstash.com/docs/workflow/basics/serve

Use the `serve()` function to define an endpoint that runs a workflow.
It accepts two arguments:

1. **Route Function**: an async function that receives the workflow context and defines the workflow steps.
2. **Options**: configuration options for the workflow.

<CodeGroup>
    ```typescript TypeScript
    import { serve } from "@upstash/workflow/nextjs";

export const { POST } = serve(async (context) => {
      // Route function
    }, {
      // Options
    });
    ```

```python Python
    from fastapi import FastAPI
    from upstash_workflow.fastapi import Serve
    from upstash_workflow import AsyncWorkflowContext

app = FastAPI()
    serve = Serve(app)

@serve.post("/api/example")
    async def example(context: AsyncWorkflowContext[str]) -> None:
        async def _step1() -> str:
            # define a piece of business logic as step 1
            return "step 1 result"

result = await context.run("step-1", _step1)

async def _step2() -> None:
            # define another piece of business logic as step 2
            pass

await context.run("step-2", _step2)
    ```
</CodeGroup>

## Route Function

The route function defines the execution logic of the workflow.
It is an async function that receives a context object, which is automatically created and passed by Upstash Workflow.

The context object provides:
* **Workflow APIs** – functions for defining workflow steps.
* **Workflow Run Properties** – request payload, request headers, and other metadata.

For a full list of available APIs and properties, see the [Workflow Context](/docs/workflow/basics/context) documentation.

<CodeGroup>
    ```typescript TypeScript highlight={4-9}
    import { serve } from "@upstash/workflow/nextjs";

export const { POST } = serve(
      async (context) => {
        // 👇 Access context properties
        const { userId } = context.requestPayload;
        // 👇 Define a workflow step
        await context.run("step-1", async () => {})
      }
    );
    ```

```python Python
    from fastapi import FastAPI
    from upstash_workflow.fastapi import Serve
    from upstash_workflow import AsyncWorkflowContext

app = FastAPI()
    serve = Serve(app)

result = await context.run("step-1", _step1)

async def _step2() -> None:
            # define another piece of business logic as step 2
            pass

await context.run("step-2", _step2)

```
</CodeGroup>

## Options

Options provide additional configuration for workflow runs.
Most of them are advanced settings and are not required for typical use cases. See [Advanced Options](/docs/workflow/basics/serve/advanced) for more details.

```typescript TypeScript highlight={5-8}
    import { serve } from "@upstash/workflow/nextjs";

export const { POST } = serve(
        async (context) => { ... },
        // 👇 Workflow options
        {
            failureFunction: async ({ ... }) => {}
        }
    );
    ```

```python Python
    from fastapi import FastAPI
    from upstash_workflow.fastapi import Serve
    from upstash_workflow import AsyncWorkflowContext

app = FastAPI()
    serve = Serve(app)

result = await context.run("step-1", _step1)

async def _step2() -> None:
            # define another piece of business logic as step 2
            pass

await context.run("step-2", _step2)

```
</CodeGroup>

# Advanced Options
Source: https://upstash.com/docs/workflow/basics/serve/advanced

Advanced Options are intended to support edge cases or testing pipelines and are **not required for regular use**.

<ParamField path="failureFunction" type="string">
    Defines a function that executes if the workflow fails after all retries are exhausted.

For details, see [failureFunction](/docs/workflow/features/failure-callback).

<CodeGroup>
        ```typescript TypeScript
        export const { POST } = serve<string>(
          async (context) => { ... },
          {
            failureFunction: async ({
              context,      // context during failure
              failStatus,   // failure status
              failResponse, // failure message
              failHeaders,  // failure headers
              failStack     // failure stack trace (if available)
            }) => {
              // handle the failure
            }
          }
        );
        ```

```python Python
        async def failure_function(
          context,       # context during failure
          fail_status,   # failure status
          fail_response, # failure message
          fail_headers   # failure headers
        ):
          # handle the failure
          pass

@serve.post("/api/example", failure_function=failure_function)
        async def example(context: AsyncWorkflowContext[str]) -> None: ...
        ```

</CodeGroup>
</ParamField>

<Note>
        This parameter is only available in Python SDK. In Javascript SDK, you can pass this value when triggering the workflow.
    </Note>

The `failureUrl` option defines an external endpoint that will be called if the workflow fails after all retries are exhausted.

This option is an advanced alternative to `failureFunction`.
    For more details, see [Advanced failureUrl Option](/docs/workflow/features/failureFunction/advanced).

```python Python
    @serve.post("/api/example", failureUrl="https://<YOUR-FAILURE-ENDPOINT>/...")
    async def example(context: AsyncWorkflowContext[str]) -> None: ...
    ```

</CodeGroup>
</ParamField>

<Note>
        This parameter is only available in Python SDK. In Javascript SDK, you can pass this value when triggering the workflow.
    </Note>

Defines the number of retry attempts if a workflow step fails.
    The default value is 3.

For details, see [retry configuration](/docs/workflow/features/retries#configuration).

```python Python
        @serve.post("/api/example", retries=3)
        async def example(context: AsyncWorkflowContext[str]) -> None: ...
        ```
    </CodeGroup>
</ParamField>

<ParamField path="middlewares" type="WorkflowMiddleware[]">
    An array of middleware instances that intercept workflow lifecycle and debug events.

Middlewares allow you to hook into various stages of workflow execution (before/after steps, run start/completion)
    and debug events (errors, warnings, info logs).

For details and examples, see [Middlewares](/docs/workflow/howto/middlewares).

```typescript TypeScript
    import { serve } from "@upstash/workflow/nextjs";
    import { loggingMiddleware } from "@upstash/workflow";

export const { POST } = serve<string>(
      async (context) => { ... },
      {
        middlewares: [loggingMiddleware]
      }
    );
    ```

</CodeGroup>
</ParamField>

<ParamField path="initialPayloadParser" type="bool">
    Enables custom parsing of the initial request payload.

Use this option if the incoming payload is not plain JSON or a simple string.
    The parser function lets you transform the raw request into a strongly typed
    object before workflow execution begins.

```typescript TypeScript
    type InitialPayload = {
      foo: string;
      bar: number;
    };

// 👇 1: provide initial payload type
    export const { POST } = serve<InitialPayload>(
      async (context) => {
        // 👇 3: parsing result is available as requestPayload
        const payload: InitialPayload = context.requestPayload;
      },
      {
        // 👇 2: custom parsing for initial payload
        initialPayloadParser: (initialPayload) => {
          const payload: InitialPayload = parsePayload(initialPayload);
          return payload;
        },
      }
    );
    ```

```python Python
    @dataclass
    class InitialPayload:
        foo: str
        bar: int

def initial_payload_parser(initial_payload: str) -> InitialPayload:
        return parse_payload(initial_payload)

@serve.post("/api/example", initial_payload_parser=initial_payload_parser)
    async def example(context: AsyncWorkflowContext[InitialPayload]) -> None:
        payload: InitialPayload = context.request_payload

```

</CodeGroup>

</ParamField>

<ParamField path="schema" type="z.ZodType">
    Alternative to `initialPayloadParser`, you can pass a `schema` in the TypeScript SDK.

The schema is used to validate and parse the initial request payload automatically using [Zod](https://zod.dev/).

```typescript TypeScript

import { z } from "zod";

const parameters = z.object({ expression: z.string() });

export const { POST } = serve(
      async (context) => {
        // context.requestPayload is typed as `{ expression: string }`
        const payload = context.requestPayload;
      },
      {
        schema: parameters,
      }
    );
    ```

</CodeGroup>
</ParamField>

<ParamField path="url" type="string">
    Specifies the full endpoint URL of the workflow, including the route path.

By default, Upstash Workflow infers the URL from `request.url` when scheduling the next step.
    However, in some environments, `request.url` may resolve to an internal or unreachable address.

Use this option when running behind a proxy, reverse proxy, or local tunnel during development where `request.url` cannot be used directly.

```typescript TypeScript
        export const { POST } = serve<string>(
          async (context) => { ... },
          {
            url: "https://<YOUR-DEPLOYED-APP>.com/api/workflow"
          }
        );
        ```

```python Python
        @serve.post("/api/example", url="https://<YOUR-DEPLOYED-APP>.com/api/workflow")
        async def example(context: AsyncWorkflowContext[str]) -> None: ...
        ```
    </CodeGroup>
</ParamField>

Similar to `url`, but `baseUrl` only overrides the base portion of the inferred URL rather than replacing the entire path.
    This is useful when you want to preserve the route structure while changing only the host or scheme.

<Tip>
        If you have multiple workflow endpoints, you can set the `UPSTASH_WORKFLOW_URL` environment variable instead of configuring `baseUrl` on each endpoint.
        The `UPSTASH_WORKFLOW_URL` environment variable corresponds directly to this option and configures it globally.
    </Tip>

```typescript TypeScript
        export const { POST } = serve<string>(
          async (context) => {
            ...
          },
          // options:
          {
            baseUrl: "<LOCAL-TUNNEL-PUBLIC-URL>"
          }
        );
        ```

```python Python
        @serve.post("/api/example", base_url="<LOCAL-TUNNEL-PUBLIC-URL>")
        async def example(context: AsyncWorkflowContext[str]) -> None: ...

```

</CodeGroup>
</ParamField>

Use `qstashClient` if you want to provide your own QStash client instead of letting Workflow use the default from environment variables.

This is useful if you're working with multiple QStash projects in the same app.

```typescript TypeScript
        import { Client } from "@upstash/qstash";
        import { serve } from "@upstash/workflow/nextjs";

export const { POST } = serve(
          async (context) => { ... },
          {
            qstashClient: new Client({ token: "<QSTASH_TOKEN>" })
          }
        );
        ```

```python Python
        from qstash import AsyncQStash

@serve.post("/api/example", qstash_client=AsyncQStash(os.environ["QSTASH_TOKEN"]))
        async def example(context: AsyncWorkflowContext[str]) -> None: ...

```

</CodeGroup>

</ParamField>

The `Receiver` verifies that every request to your endpoint actually comes from QStash, blocking anyone else from triggering your workflow.

The `receiver` option allows you to pass a QStash Receiver explicitly.

By default, Workflow initializes the Receiver automatically using the environment variables `QSTASH_CURRENT_SIGNING_KEY` and `QSTASH_NEXT_SIGNING_KEY`.

This is useful if you're working with multiple QStash projects in the same app.

```typescript TypeScript
        import { Receiver } from "@upstash/qstash";
        import { serve } from "@upstash/workflow/nextjs";

export const { POST } = serve<string>(
          async (context) => { ... },
          {
            receiver: new Receiver({
              currentSigningKey: "<QSTASH_CURRENT_SIGNING_KEY>",
              nextSigningKey: "<QSTASH_NEXT_SIGNING_KEY>",
            })
          }
        );
        ```

```python Python
        from qstash import Receiver

@serve.post(
            "/api/example",
            receiver=Receiver(
                current_signing_key=os.environ["QSTASH_CURRENT_SIGNING_KEY"],
                next_signing_key=os.environ["QSTASH_NEXT_SIGNING_KEY"],
            ),
        )
        async def example(context: AsyncWorkflowContext[str]) -> None:
            ...
        ```

</CodeGroup>

</ParamField>

By default, Workflow uses `process.env` to read credentials and initialize QStash.
If you're in an environment where `process.env` isn't available, or you want to inject values manually, you can pass them with `env`.

Inside your workflow, these values are also exposed on `context.env`.

```typescript TypeScript
import { Receiver } from "@upstash/qstash";
import { serve } from "@upstash/workflow/nextjs";

export const { POST } = serve<string>(
  async (context) => {
    // the env option will be available in the env field of the context:
    const env = context.env;
  },
  {
    env: {
        QSTASH_URL: "<QSTASH_URL>",
        QSTASH_TOKEN: "<QSTASH_TOKEN>",
        QSTASH_CURRENT_SIGNING_KEY: "<QSTASH_CURRENT_SIGNING_KEY>",
        QSTASH_NEXT_SIGNING_KEY: "<QSTASH_NEXT_SIGNING_KEY>",
    }
  }
);
```

```python Python
@serve.post(
    "/api/example",
    env={
        "QSTASH_CURRENT_SIGNING_KEY": os.environ["QSTASH_CURRENT_SIGNING_KEY"],
        "QSTASH_NEXT_SIGNING_KEY": os.environ["QSTASH_NEXT_SIGNING_KEY"],
    },
)
async def example(context: AsyncWorkflowContext[str]) -> None:
    ...
```

</CodeGroup>

</ParamField>

Enables verbose mode to print detailed logs of workflow execution to the application's `stdout`.

Verbose mode is disabled by default.

```typescript
    export const { POST } = serve<string>(
      async (context) => { ... },
      {
        verbose: true
      }
    );
    ```

</ParamField>

<ParamField path="disableTelemetry" type="boolean">
    Disables anonymous telemetry data collection for this workflow endpoint. Since we don't collect telemetry
    in Python SDK, this option is only available in the TypeScript SDK.

By default, the Upstash Workflow SDK collects anonymous telemetry data to help improve the service.
    The collected data includes:

* SDK version
    * Platform (Vercel, AWS, etc.)
    * Runtime version (Node.js, Python, etc.)

Set `disableTelemetry` to `true` to opt out of telemetry for this specific workflow endpoint.

```typescript TypeScript
        export const { POST } = serve<string>(
          async (context) => { ... },
          {
            disableTelemetry: true
          }
        );
        ```

```python Python
        @serve.post("/api/example", disable_telemetry=True)
        async def example(context: AsyncWorkflowContext[str]) -> None: ...
        ```
    </CodeGroup>

<Tip>
        You should also
        set [`disableTelemetry` when triggering workflow runs via `client.trigger()`](/docs/workflow/basics/client/trigger#param-disable-telemetry) to fully disable telemetry
    </Tip>
</ParamField>

# Changelog
Source: https://upstash.com/docs/workflow/changelog

<Note>
  We have moved the roadmap and the changelog to [Github Discussions](https://github.com/orgs/upstash/discussions) starting from October 2025.Now you can follow `In Progress` features. You can see that your `Feature Requests` are recorded. You can vote for them and comment your specific use-cases to shape the feature to your needs.
</Note>

<Update label="June 2026">
* **TypeScript SDK (`workflow-js`):**
    * Multiple labels per workflow run are now supported. `label` on [`client.trigger`](/docs/workflow/basics/client/trigger) and `context.invoke` accepts `string | string[]`, and log/DLQ/cancel filters accept an array to match runs that have any of the given labels (OR semantics). Workflow run logs now expose a `labels: string[]` field, and `context.labels: string[]` replaces the now-deprecated `context.label`.
</Update>

<Update label="March 2026">
* **TypeScript SDK (`workflow-js`):**
    * Added optional `workflowRunId` parameter to `notify` method, enabling **lookback functionality**. When provided, notifications are stored and delivered even if sent before a workflow reaches `waitForEvent`, preventing race conditions. See [notify documentation](/docs/workflow/basics/client/notify) and [wait-for-event guide](/docs/workflow/features/wait-for-event#race-condition-between-wait-and-notify) for details.
</Update>

<Update label="September 2025">
* **TypeScript SDK (`workflow-js`):**
    * `Label` feature is added. This will enable our users to label their workflow runs so that
        * Logs can be filtered with user given label.
        * DLQ can be filtered with user given label.
    * `notBefore` parameter is added to `trigger` function that will allow starting a workflow run at a later date
    given by the `notBefore` parameter.
* **Console:**
    * A major Workflow redesign is landed to improve debugging and monitoring experience workflow runs logs.
        * `Flat view` is removed. All the data is moved to single view. This is also to avoid confusing our
        users and made over all experience simpler.
</Update>

<Update label="August 2025">
* **TypeScript SDK (`workflow-js`):**
    * Added `retryDelay` option to dynamicaly program the retry duration. It can be configured on
    [trigger](/docs/workflow/basics/client#trigger-workflow) , [context.call](/docs/workflow/basics/context#context-call)
    or [serve](/docs/workflow/basics/serve#retrydelay)
    * Added ability to detect if a given url is a workflow or not. Starting with `0.2.17` trigger made via the sdk can fail (instead of hanging),
    if there is no workflow serve on the given url.
* **Console:**
    * Local mode is added to enable our users to use the console with their local development envrionment and the locally deployed workflows.
    See [docs](/docs/workflow/howto/local-development#development-server-recommended) for details.
</Update>

<Update label="July 2025">
* **TypeScript SDK (`workflow-js`):**
    * Restart/Resume for DLQ is added to allow more options to handle failed runs. See [here](/docs/workflow/howto/failures#manually-handling-failed-workflow-runs)
    * Added `WorkflowNonRetryableError` to fail a workflow without causing any retries. See [here](/docs/workflow/basics/context#error-handling-and-retries)
    * For additional bug fixes, see the full changelog [here](https://github.com/upstash/workflow-js/compare/v0.2.14...v0.2.16).
</Update>

<Update label="June 2025">
* **TypeScript SDK (`workflow-js`):**
    * Added `useFailureFunction` and `failureFunction` to `client.trigger`. See [here](https://github.com/upstash/workflow-js/pull/107).
    * Added batch triggering support to `client.trigger`. See [here](https://github.com/upstash/workflow-js/pull/110).
    * For additional bug fixes, see the release notes [here](https://github.com/upstash/workflow-js/releases/tag/v0.2.14).
* **Python SDK (`workflow-py`):**  
    * Failure function is implemented. This feature enables to act on a failure of a workflow on the code. See docs [here](/docs/workflow/howto/failures#using-a-failurefunction-recommended)
    * For other bug fixes, see the full changelog [here](https://github.com/upstash/workflow-py/compare/v0.1.0...v0.1.1).
* **Console:**
    * A major redesign is coming next month to improve Workflow usability.
* **Workflow Server:**  
    * An issue causing Workflows not usable with `CloudFront` is fixed.
</Update>

<Update label="May 2025">
* **TypeScript SDK (`workflow-js`):**
    * Added a `workflow` parameter to `context.call`, enabling type-safe workflow calls. See [here](https://github.com/upstash/workflow-js/pull/75).
    * Enabled passing `context.call` settings when defining an Agent. See [here](https://github.com/upstash/workflow-js/pull/90).
    * Added `delay` support to `client.trigger`. See [here](https://github.com/upstash/workflow-js/pull/100).
    * Introduced `period` and improved `rate` support in flow control. See [here](https://github.com/upstash/workflow-js/pull/101).
      Previously, `period` was fixed at 1 second. For example, `rate: 3 period: 1d` throttles publishes to 3 per day.
    * For additional bug fixes, see the release notes [here](https://github.com/upstash/workflow-js/releases/tag/v0.2.13).
* **Workflow Server:**
    * Added support for custom `period` in flow control, allowing users to set a period of up to 1 week.
      Previously, `period` was fixed at 1 second. For example, `rate: 3 period: 1d` throttles publishes to 3 per day.
    * Implemented **Workflow Resume** and **Restart** features (SDK and Console support in progress):
        * **Resume** allows users to retry a workflow run from the point it stopped.
        * **Restart** allows users to retry a workflow run from the beginning.
* **Console:**
    * A major redesign is coming to improve Workflow usability.
</Update>

<Update label="April 2025">
* **Python SDK (`workflow-py`):**  
    * Minor bug fixes.
      See the full changelog [here](https://github.com/upstash/workflow-py/compare/v0.1.0...v0.1.1).
* **Workflow Server:**
    * Prevented intermediate Workflow calls from failing due to request/message quota limits.
    * Fixed handling of `RUN_STARTED` so that it correctly returns unfinished Workflow Runs as documented.
      Previously, some Workflow Runs could be skipped if internal state was logged after `RUN_STARTED`.
    * Applied several performance optimizations.
</Update>

<Update label="March 2025">
* **TypeScript SDK (`workflow-js`):**
	* Added `onError` support to `serve` by the community. See [here](https://github.com/upstash/workflow-js/pull/79).
    * Enabled support for all fetch-compatible models in Agents. See [more details here](https://github.com/upstash/workflow-js/pull/77).
    * For additional bug fixes, see the full changelog [here](https://github.com/upstash/workflow-js/compare/v0.2.11...v0.2.12).
</Update>

<Update label="February 2025">
* **TypeScript SDK (`workflow-js`):**
	* Fixed a Unicode issue in `context.call` where binary responses from endpoints could break. See [here](https://github.com/upstash/workflow-js/pull/71).
    * Introduced `WorkflowTool`, allowing Workflow Agents to define multi-step workflows as a tool. See [here](/docs/workflow/agents/features#tools).
    * Added `context.invoke` to call one workflow from another with full type-safety. See the guide [here](/docs/workflow/features/invoke).
    * Introduced flow control parameters to limit the rate or concurrency of workflow runs. Learn more [here](/docs/workflow/features/flow-control).
    * For additional bug fixes, see the full changelog [here](https://github.com/upstash/workflow-js/compare/v0.2.3...v0.2.6).
* **Workflow Server:**
    * Added RateLimit and Parallelism controls to manage the frequency and concurrency of workflow runs. Learn more [here](/docs/workflow/features/flow-control).
</Update>

<Update label="January 2025">
* **TypeScript SDK (`workflow-js`):**
    * Added the Agents API to workflows. You can now create AI agents to run workflows on your own infrastructure with all the benefits of workflows: reduced environment costs, fault tolerance, and scalability. Learn more about agents [here](/docs/workflow/agents/overview).
    * For other bug fixes, see the full changelog [here](https://github.com/upstash/workflow-js/compare/v0.2.3...v0.2.6).
* **Python SDK (workflow-py):**
    * Released [`workflow-py`](https://github.com/upstash/workflow-py).
* **Local Development Server:**
    * The local development server is now available for public use. This server allows you to test your workflows locally. Learn more about the local development server [here](/docs/workflow/howto/local-development#development-server-recommended).
* **Console:**
    * Separated Workflow and QStash consoles for a better user experience.
    * Separated their DLQ messages as well.
* **Workflow Server:**
    * The core team focused on RateLimit and Parallelism features. These features are ready on the server and will be announced next month after the documentation and SDKs are completed.
</Update>

<Update label="December 2024">
* **TypeScript SDK (`workflow-js`):**
    * Introduced third-party integrations, starting with Anthropic, Resend, and OpenAI. These integrations are automatically offloaded to workflows, ensuring long-running calls do not consume user environment time. See the related documentation [here](/docs/workflow/basics/context#context-api).
    * Added a `timeout` parameter to `context.call`. Learn more in the [documentation](/docs/workflow/basics/context#context-call).
    * Improved support for workflows in Express and SvelteKit by adding the `useJSONContent` option.
    * Resolved loop detection issues on Cloudflare and Render.
    * Full changelog, including all fixes, is available [here](https://github.com/upstash/workflow-js/compare/v0.2.0...v0.2.3).

* **Workflow Server:**
    * Added the `WorkflowCreatedAt` filter for Dead Letter Queue (DLQ) and Events.
    * Prepared the local development server for public release (coming soon).
    * Enhanced `context.SleepUntil` to support float values.
    * Increased the event retention period from 10,000 events to up to 14 days. Learn more on the [Pricing page](https://upstash.com/pricing/workflow).
</Update>

<Update label="November 2024">
* **Python SDK (workflow-py):**
    * Began development of the Python SDK.
* **TypeScript SDK (workflow-js):**
    * Added support for string durations (e.g., `1d`, `30s`) in `context.sleep` and `context.waitForEvent`.
    * Introduced integrations for [Astro](/docs/workflow/quickstarts/astro) and [Express](/docs/workflow/quickstarts/express).
    * Added `client.trigger`, enabling workflows to start and return the workflow run ID. See the [documentation](/docs/workflow/basics/client#trigger-workflow).
    * Added a retry option for `context.call`. See the [documentation](/docs/workflow/basics/context#context-call).
    * Introduced a lazy fetch feature to support longer and larger workflows on resource-limited platforms.
    * Added `context.cancel` to cancel the current workflow. See the [documentation](/docs/workflow/basics/context#context-cancel).
    * Full changelog, including fixes, is available [here](https://github.com/upstash/workflow-js/compare/v0.1.2...v0.2.0).
* **Workflow Server:**
    * Added bulk cancel functionality for workflow runs. See the [REST API](/docs/workflow/api-reference/runs/bulk-cancel-workflow-runs).
    * Introduced content-based deduplication for workflows and retry-until-success functionality. This will allow workflows to be used in areas with unstable network connection.
</Update>

<Update label="October 2024">
* Optimized the console by trimming event bodies, reducing resource usage and enabling efficient querying of events with large payloads.
* Began development on a new architecture to deliver faster event processing on the server.
* Added [Wait Notify](/docs/workflow/features/wait-for-event) feature.
</Update>

<Update label="September 2024">
* Bug fixes and internal logging improvements.
</Update>

<Update label="August 2024">
* Released [Upstash Workflow](/docs/workflow/getstarted).
</Update>

- [AI Generation](https://upstash.com/docs/workflow/examples/allInOne.md)
- [Auth Provider Webhook](https://upstash.com/docs/workflow/examples/authWebhook.md)
- [Custom Retry Logic](https://upstash.com/docs/workflow/examples/customRetry.md)
- [Customer Onboarding](https://upstash.com/docs/workflow/examples/customerOnboarding.md)
- [Dynamic Workflows](https://upstash.com/docs/workflow/examples/dynamicWorkflow.md)
- [E-commerce Order Fulfillment](https://upstash.com/docs/workflow/examples/eCommerceOrderFulfillment.md)
- [Image Processing](https://upstash.com/docs/workflow/examples/imageProcessing.md)
- [Payment Retries](https://upstash.com/docs/workflow/examples/paymentRetry.md)
- [Waiting for Events](https://upstash.com/docs/workflow/examples/waitForEvent.md)

# Overview
Source: https://upstash.com/docs/workflow/features/dlq

The Dead Letter Queue (DLQ) automatically captures failed workflow runs that have exhausted all retry attempts.

This ensures that no workflow execution is lost and provides multiple options for recovering from failures gracefully.

## How it works?

When a workflow step fails and exhausts all configured retries, Upstash Workflow automatically moves the failed run to the DLQ.
This happens automatically without any additional configuration required.

<img />

The DLQ serves as a safety net, preserving failed workflow runs with their complete execution context.

<Note>
   Dead Letter Queue entries have retention period based on your pricing plan:
  * **Free**: 3 days
  * **Pay-as-you-go**: 1 week
  * **Fixed pricing**: Up to 3 months

After the retention duration expires, DLQ items are automatically removed and cannot be recovered.
</Note>

## Recovery Actions

Once a workflow run is in the DLQ, you can take the following actions:

* **[Restart](/docs/workflow/features/dlq/restart)** – trigger the workflow from the beginning.
* **[Resume](/docs/workflow/features/dlq/resume)** – continue the workflow from the point of failure.
* **[Re-run Failure Function](/docs/workflow/features/dlq/callback)** – execute the workflow's failure handling logic again.
* **[Delete](/docs/workflow/features/dlq/delete)** – remove the DLQ entry if no action is required.

You can apply these actions in bulk to multiple DLQ entries. Check the individual action pages for more details.

# Rerun Failure Function
Source: https://upstash.com/docs/workflow/features/dlq/callback

The **Rerun Failure Function** action allows you to retry the failure function that executes when a workflow run enters the Dead Letter Queue (DLQ).

The failure function is typically a cleanup or notification operation that runs automatically whenever a workflow is moved to the DLQ.

This feature is particularly helpful for:

* Ensuring that important cleanup operations are executed.
* Guaranteeing that logging or alerting is completed after a workflow failure.
* Recovering from temporary errors in the failure function itself.

By manually rerunning this function, you can ensure that critical operations—such as cleanup tasks, logging, or alerting—complete successfully even if the main workflow has failed.

<img />

You can perform this action programmatically as well:

<CodeGroup>
    ```typescript TypeScript
    import { Client } from "@upstash/workflow";

const client = new Client({ token: "<WORKFLOW_TOKEN>" });

await client.dlq.retryFailureFunction({
      dlqId: "dlq-12345",
    });
    ```
</CodeGroup>

<Note>
    This action is only available if the failure function itself has failed as well.
    If the failure function already succeeded, it cannot be rerun.

You can view the status of the failure function in the **DLQ** and **Logs** dashboards, which indicate whether it succeeded or failed.
</Note>

# Delete
Source: https://upstash.com/docs/workflow/features/dlq/delete

The **Delete** action allows you to remove failed workflow runs from the Dead Letter Queue when no recovery action is needed.

You can delete entries individually, in bulk by IDs, or by using filters such as label, URL, or date range.

<CodeGroup>
    ```typescript TypeScript
    import { Client } from "@upstash/workflow";

const client = new Client({ token: "<WORKFLOW_TOKEN>" });

// delete a single entry
    await client.dlq.delete("dlq-12345");

// delete multiple entries
    await client.dlq.delete(["dlq-12345", "dlq-67890"]);

// delete by filters
    await client.dlq.delete({ label: "my-label" });

// delete all
    await client.dlq.delete({ all: true });
    ```
</CodeGroup>

For the full API reference, see [client.dlq.delete](/docs/workflow/basics/client/dlq/delete).

# Restart
Source: https://upstash.com/docs/workflow/features/dlq/restart

The **Restart** action allows you to re-execute a failed workflow run from the beginning.
All previous step results are discarded, and the workflow executes from scratch using the original configuration and initial payload.

This approach is ideal when:

* Previous step results are no longer relevant.
* The failure was caused by corrupted or inconsistent state.
* You need a completely fresh execution with updated or clean data.

<img />

You can perform this action programmatically as well:

<CodeGroup>
    ```typescript TypeScript
    import { Client } from "@upstash/workflow";

const client = new Client({ token: "<WORKFLOW_TOKEN>" });

await client.dlq.restart({
      dlqId: "dlq-12345",
      retries: 3,
    });
    ```
</CodeGroup>

# Resume
Source: https://upstash.com/docs/workflow/features/dlq/resume

The **Resume** action allows you to continue a failed workflow run from the exact point of failure, preserving all successfully completed steps and their results.

This approach is ideal when:

* The workflow has long-running or resource-intensive steps that have already succeeded.
* You want to preserve progress and avoid re-executing successful operations.
* The failure was a temporary issue that can now be resolved.

<img />

You can perform this action programmatically as well:

<CodeGroup>
    ```typescript TypeScript
    import { Client } from "@upstash/workflow";

const client = new Client({ token: "<WORKFLOW_TOKEN>" });

await client.dlq.resume({
      dlqId: "dlq-12345",
      retries: 3,
    });
    ```
</CodeGroup>

<Note>
    You can modify workflow code as long as changes occur **after** the failed steps.
    Changes to steps prior to the failure are not allowed and may break the workflow.

For more details, check out the [Handle workflow route code changes](/docs/workflow/howto/changes) page.
</Note>

# Overview
Source: https://upstash.com/docs/workflow/features/failure-callback

When you define a workflow endpoint, you can attach a failure function to the workflow that allows you to execute custom logic when a workflow run fails after exhausting all retry attempts.

This feature ensures that you can perform cleanup operations, logging, alerting, or any other custom error handling logic before the failed workflow run is moved to the Dead Letter Queue (DLQ).

<img />

The failure function automatically receives the workflow run context and the reason for the failure, so you can decide how to handle it.

<CodeGroup>
```typescript TypeScript
import { serve } from "@upstash/workflow/nextjs";

export const { POST } = serve<string>(
  async (context) => {
    // Your workflow logic...
  },
  {
    failureFunction: async ({
      context,
      failStatus,
      failResponse,
      failHeaders,
    }) => {

// 👇 Log error to monitoring system
      await logToSentry(...);

// 👇 Send alert to team
      await sendSlackAlert(...);

// 👇 Perform cleanup operations
      await cleanupWorkflowResources(...);
    },
  }
```
);

</CodeGroup>

You cannot create new workflow steps inside the `failureFunction` using `context`.
The `context` provided here is only meant to expose workflow run properties (like URL, payload, and headers).
Think of the failure function as an individual `context.run` step. It executes once with the provided context but cannot define further steps.

<Info>
    If you use a custom authorization method to secure your workflow endpoint, add authorization to the `failureFunction` too.
    Otherwise, anyone could invoke your failure function with a request.

Read more here: [securing your workflow endpoint](/docs/workflow/howto/security).
</Info>

## Parameters

The `failureFunction` receives an object with the following parameters:

<ParamField body="context" type="object">
    The workflow context object containing:

<Expandable>
        <ParamField body="workflowRunId" type="string">
            The ID of the failed workflow run
        </ParamField>

<ParamField body="url" type="string">
            The publicly accessible workflow endpoint URL
        </ParamField>

<ParamField body="requestPayload" type="string">
            The original request payload that triggered the workflow
        </ParamField>

<ParamField body="headers" type="string">
            The original request headers
        </ParamField>

<ParamField body="env" type="string">
            Environment variables
        </ParamField>
    </Expandable>
</ParamField>

<ParamField body="failStatus" type="number">
    The HTTP status code returned by the failed workflow step.
</ParamField>

<ParamField body="failResponse" type="number">
    The response body returned by the failed workflow step.
</ParamField>

<ParamField body="failHeaders" type="number">
    The response headers returned by the failed workflow step.
</ParamField>

# Advanced failureUrl Option
Source: https://upstash.com/docs/workflow/features/failureFunction/advanced

The `failureUrl` is an advanced option that sends failure callback to a different endpoint rather than to the workflow endpoint (failure function).
This approach is useful for handling failures on separate infrastructure.

<Tip>You can use either `failureFunction` or `failureUrl`, but not both. These options are mutually exclusive.</Tip>

For most users, **Failure Function** is the better choice because:
* It runs alongside your workflow and has access to the same context and dependencies
* Failure function requests are automatically retried on failure as well.
* You can manually retry failure function if it fails via DLQ.

If you think this advanced option fits your need, you can configure it by passing `failureUrl` configuration.

<CodeGroup>
    ```typescript
    import { Client } from "@upstash/workflow";

const client = new Client({ token: "<QSTASH_TOKEN>" })

const { workflowRunId } = await client.trigger({
      url: "https://<YOUR_WORKFLOW_URL>/workflow"
      failureUrl: "https://<YOUR_FAILURE_URL>/workflow-failure"
    })
    ```

```python Python
    @serve.post("/api/example", failure_url="https://<YOUR_FAILURE_URL>/workflow-failure")
    async def example(context: AsyncWorkflowContext[str]) -> None:
        # Your workflow logic...
        pass
    ```
</CodeGroup>

# Reliability of Failure Function
Source: https://upstash.com/docs/workflow/features/failureFunction/reliability

The failure function is executed whenever a workflow run fails.

In some cases, the failure function itself may throw an error.
When this happens, it will be retried according to the workflow run's retry configuration.
If all retry attempts also fail, the failure function execution is marked as failed.

You can view and filter workflow runs with failed failure function executions in the DLQ dashboard.

<img />

From the DLQ dashboard, you can retry the failure function.

<img />

You can perform this action programmatically as well:

```ts
import { Client } from "@upstash/workflow";

const client = new Client({ token: "<QSTASH_TOKEN>" });

const response = await client.dlq.retryFailureFunction({
  dlqId: "dlq-12345" // The ID of the DLQ message to retry
});
```

# Overview
Source: https://upstash.com/docs/workflow/features/flow-control

Flow Control allows you to limit how many workflow steps are executed by delaying and queuing their delivery.

This feature helps to:
* Manage resource consumption
* Prevent violations of external API rate limits
* Ensure workflows run within defined system constraints

## How Flow Control Works

When defined limits are exceeded, Flow Control automatically queues and delays step executions instead of rejecting them.
This guarantees that all steps are eventually processed while staying within configured thresholds.

To configure Flow Control, you define a flow control key, a unique identifier used to group related steps under the same rate and parallelism limits.
The steps that has the same flow control key respect the same constraints.

There are two main parameters to configure:

* [Rate and Period](/docs/workflow/features/flow-control/rate-period): Maximum number of steps that may start within a time window
* [Parallelism](/docs/workflow/features/flow-control/parallelism): Maximum number of steps allowed to run concurrently

These parameters can be combined for fine‑grained control.
For example, you can allow up to 10 steps per minute but restrict concurrency
to 5 steps in parallel, ensuring more predictable load patterns.

## Example

Suppose you have the following workflow:

```typescript
export const { POST } = serve<{ topic: string }>(async (context) => {
  const payload = context.requestPayload

await context.run("step-1", () => { ... });

await context.run("step-2", () => { ... });

await context.run("step-3", () => { ... });
})
```

Now imagine you trigger **N workflow runs** for this workflow with the following configuration:

```typescript
const { workflowRunId } = await client.trigger({
  url: "https://<YOUR_WORKFLOW_ENDPOINT>/<YOUR-WORKFLOW-ROUTE>",
  flowControl: {
    key: "fw_example",
    parallelism: 7,
    rate: 3,
    period: "1m",
  }
})
```

Without Flow Control, all workflow runs immediately execute their steps as soon as possible.
If the workflow calls an external API in a step, this would likely result in ~N concurrent requests being fired in a very short timeframe, potentially overloading services or breaching API limits.

<img />

With the configuration above:
* **Rate:** At most 3 steps per minute can start across all workflow runs.
* **Parallelism:** At most 7 steps can be running at the same time.

Steps that exceed these limits are automatically queued and executed later.

<img />

Note that each step above corresponds to a separate workflow run.
Because this workflow is sequential, each workflow run has only one pending step at a time.
In workflows with **parallel branches**, multiple steps from the same workflow run may appear in the schedule simultaneously.

Parallelism slots are consumed by running steps.
If no slots are available, new steps enter the **waitlist** until resources free up:

<img />

<Note>
Upstash Workflow does not support per-step level configuration. Meaning that you can attach a flow-control configuration
to the workflow run and all the steps will inherit to the same limits.
Following the analogy above, you cannot enforce parallelism limit on "green" steps natively.

The context.call and context.invoke steps are exception this to this rule and accept their own flow control configuration:

* [context.call](/docs/workflow/basics/context/call) – lets you run external HTTP requests under a separate key, so you can throttle third‑party API calls independently of your workflow logic.
* [context.invoke](/docs/workflow/basics/context/invoke) – starts a new workflow run with its own flow control configuration. This allows the invoked workflow to run under different limits than the parent workflow, giving you more precise control.

If you want to throttle a specific `context.run` step, the recommended approach is to **extract it into a separate workflow** and call it using `context.invoke()` with its own flow control configuration with a stricter limits.
</Note>

## Configuration

You can configure flow control when starting a workflow run:

```typescript Configure Retry Attempt Count
import { Client } from "@upstash/workflow";

const client = new Client({ token: "<QSTASH_TOKEN>" })

const { workflowRunId } = await client.trigger({
  url: "https://<YOUR_WORKFLOW_ENDPOINT>/<YOUR-WORKFLOW-ROUTE>",
  flowControl: {
    key: "user-signup",
    parallelism: 1,
    rate: 10,
    period: 100,
  }
})
```

All steps within a workflow run will adhere to the specified flow control configuration.

<Warning>
Keep in mind that rate/period and parallelism info are kept on each step separately.
If you change the rate/period or parallelism on a new deployment, the old fired ones will not be affected.
They will keep their flow control configuration.

During the period that old steps have not been delivered but there are also steps with new rates, Upstash Workflow will effectively allow the highest rate/period or highest parallelism. Eventually (after the old publishes are delivered), the new rate/period and parallelism will be used.
</Warning>

# Monitor & Manage
Source: https://upstash.com/docs/workflow/features/flow-control/monitor

You can monitor wait list size of your flow control key's from the console `FlowControl` tab. The console also allows you to pin, unpin, and reset rate for flow control keys directly.

<img />

Also you can get the same info using the REST API.
* [List All Flow Control Keys](/docs/workflow/api-reference/flow-control/list-flow-control-keys).
* [Single Flow Control Key](/docs/workflow/api-reference/flow-control/get-flow-control-key).
* [Global Parallelism](/docs/workflow/api-reference/flow-control/get-global-parallelism).

## Manage

You can manage flow control keys by pausing/resuming delivery, pinning/unpinning configurations, and resetting rate counts.

These operations are available via the SDK, REST API, or directly from the **Flow Control** tab in the [Upstash Console](https://console.upstash.com).

Since Upstash Workflow uses QStash under the hood, flow control management is done through the QStash client. See the [QStash Flow Control Management API](/docs/qstash/features/flowcontrol#management-api) for full details and code examples.

# Parallelism
Source: https://upstash.com/docs/workflow/features/flow-control/parallelism

The parallelism limit controls the maximum number of calls that can be executed concurrently.
Unlike rate limiting (which works per time window), parallelism enforces concurrency control with a token-based system.

```typescript Configure Retry Attempt Count
import { Client } from "@upstash/workflow";

const client = new Client({ token: "<QSTASH_TOKEN>" })

const { workflowRunId } = await client.trigger({
  url: "https://<YOUR_WORKFLOW_ENDPOINT>/<YOUR-WORKFLOW-ROUTE>",
  flowControl: {
    key: "user-signup",
    parallelism: 10,
  }
})
```

**Example**:
If `parallelism = 3`, at most 3 requests can run concurrently.

When tokens are available, requests acquire one and start execution:
  <img />

When all tokens are in use, additional requests are not failed — they’re queued in a **waitlist**:
  <img />

The step in the waitlist will wait for a step to complete and hand off it's token to a pending request:

<Tip>
    Token handoff does not guarantee strict ordering.
    A later request in the waitlist may acquire a token before an earlier one.
</Tip>

<img />

# Rate and Period
Source: https://upstash.com/docs/workflow/features/flow-control/rate-period

The rate specifies the maximum number of requests allowed in a given period (time window).

```typescript Configure Retry Attempt Count
import { Client } from "@upstash/workflow";

const client = new Client({ token: "<QSTASH_TOKEN>" })

const { workflowRunId } = await client.trigger({
  url: "https://<YOUR_WORKFLOW_ENDPOINT>/<YOUR-WORKFLOW-ROUTE>",
  flowControl: {
    key: "user-signup",
    rate: 10,
    period: 100,
  }
})
```

**Example**:
If `rate = 2` and `period = 1 minute`, then **a maximum of 2 steps** can be executed per minute.

The first 2 requests within the minute are executed immediately:

<img />

The 3rd request in the same minute is not executed immediately:

<img />

Instead of rejecting it, Workflow schedules the request in the next available time window:

<img />

Note that step executions may take longer than the defined period.
The rate limit only controls how many steps are **started** within each time window,
it does not limit their execution duration.

# Overview
Source: https://upstash.com/docs/workflow/features/invoke

You can start another workflow run inside a workflow and await its execution to complete.
This allows to orchestrate multiple workflows together without external synchronization.

When you use `context.invoke`, invoking workflow will wait until the invoked workflow finishes before running the next step.

```typescript
const {
  body,      // response from the invoked workflow
  isFailed,  // whether the invoked workflow was canceled
  isCanceled // whether the invoked workflow failed
} = await context.invoke(
  "analyze-content",
  {
    workflow: analyzeContent,
    body: "test",
    header: {...}, // headers to pass to anotherWorkflow (optional)
    retries,       // number of retries (optional, default: 3)
    flowControl,   // flow control settings (optional)
    workflowRunId  // workflowRunId to set (optional)
  }
)
```

You can return a response from a workflow, which will be delivered to invoker workflow run.

<img />

<Note>
    You cannot create an infinite chain of workflow invocations. If you set up an 'invoke loop' where workflows continuously invoke each other, the process will fail once it reaches a depth of 100.
</Note>

# Using Serve Many
Source: https://upstash.com/docs/workflow/features/invoke/serveMany

Normally, workflows are created with `serve()`, which exposes each workflow as its own HTTP endpoint.
If workflows were invoked only by their full URL, it would mean:

* You'd have to provide the URL explicitly like a trigger request
* You'd lose type safety for request and response payloads

To avoid these issues, Upstash Workflow lets you define workflows as objects and expose them under the same parent path.
This way, you can invoke a workflow simply by passing the object to `context.invoke`, with full type safety and no URLs required.

<Steps>
  <Step title="Create workflow objects">
    Use `createWorkflow()` to define workflows as objects.

It works just like `serve()`—accepting the same arguments—but does **not** expose the workflow directly as an HTTP endpoint.
    Instead, it simply initializes a workflow object.

```typescript
    const workflowOne = createWorkflow(
      // 👇 Request Payload Type
      async (context: WorkflowContext<string>) => {

await context.sleep("wait 1 second", 1)

// 👇 Workflow Response Type
        return { message: "This is the data returned by the workflow" };
      }
    );

const workflowTwo = createWorkflow(async (context) => {
      // 👇 Invoke the workflow with type-safe call
      const { body } = await context.invoke(
        "invoke workflowOne",
        {
          workflow: workflowOne,
          body: "user-1"
        }
      ),
    });
    ```
  </Step>
  <Step title="Expose multiple workflows under same endpoint">
    Use `serveMany()` instead of `serve()` to expose multiple workflows on a single catch‑all route.

If one workflow is going to invoke another, both must be included in the same `serveMany` definition.
    First step of using `serveMany` is to define a catch-all route.

```typescript  app/serve-many/[...any]/route.ts
    export const { POST } = serveMany(
      {
        "workflow-one-route": workflowOne,
        "workflow-two-route": workflowTwo,
      }
    )
    ```

<Info>
        In Next.js, a catch‑all route can be defined by creating a `route.ts` file inside a directory named with `[...]`, for example: `app/serve-many/[...any]/route.ts`.

For implementations of `serveMany` in other frameworks, you can refer to the projects available in the [`examples` directory of the workflow-js repository](https://github.com/upstash/workflow-js/tree/main/examples).
    </Info>
  </Step>
  <Step title="Invoke by passing workflow object">
    When invoking, pass the workflow object created with `createWorkflow()` (from step 1) as the argument to `context.invoke()`.
    This removes the need to specify a URL explicitly and ensures the call is
    fully type‑safe.

```ts
    const workflowTwo = createWorkflow(async (context) => {
      // 👇 Invoke the workflow with type-safe call
      const { body } = await context.invoke(
        "invoke workflowOne",
        {
          // 👇 Pass the workflow object as argument
          workflow: workflowOne,
          body: "user-1"
        }
      ),
    });
    ```

</Step>

<Step title="Trigger">
    In this example, both `workflowOne` and `workflowTwo` are exposed through `serveMany`, sharing the same parent path.

You can start `workflowOne` by sending a trigger request to:
    `https://your-app/serve-many/workflow-one-route`.

```typescript
    import { Client } from "@upstash/workflow";

const client = new Client({ token: "<QSTASH_TOKEN>" })

const { workflowRunId } = await client.trigger({
      // 👇 URL of workflow one
      url: "https://your-app/serve-many/workflow-one-route"
    })
    ```

Route names are inferred from the keys you pass to `serveMany`.
    For example, you can start `workflowTwo` by sending trigger request to: `https://your-app/serve-many/workflow-two-route`.
    </Step>
</Steps>

# Notify
Source: https://upstash.com/docs/workflow/features/notify

You can notify all the workflow runs waitingi for a specific event ID.
There are two ways to send a notify request.

## Notify within Workflow

Notifies other workflows waiting for a specific event from within a workflow.

<CodeGroup>
```typescript TypeScript
import { serve } from "@upstash/workflow/nextjs";

export const { POST } = serve<string>(async (context) => {
  const { orderId, processingResult } = context.requestPayload;

await context.run("process-order", async () => {
    // ...
  })

const { notifyResponse } = await context.notify(
    "notify-processing-complete",
    `order-${orderId}`,
    {
      orderId,
      status: "completed",
      result: processingResult,
      completedAt: new Date().toISOString()
    }
  );

});
```

```python Python
from fastapi import FastAPI
from upstash_workflow.fastapi import Serve
from upstash_workflow import AsyncWorkflowContext
from datetime import datetime

app = FastAPI()
serve = Serve(app)

@serve.post("/api/order-processor")
async def order_processor(context: AsyncWorkflowContext[str]) -> None:
    order_id = context.request_payload["order_id"]
    processing_result = context.request_payload["processing_result"]

# Process the order
    async def _process_order():
        return await process_order(order_id)

result = await context.run("process-order", _process_order)

# Notify waiting workflows that processing is complete
    notify_response = await context.notify(
        "notify-processing-complete",
        f"order-{order_id}",
        {
            "order_id": order_id,
            "status": "completed",
            "result": processing_result,
            "completed_at": datetime.utcnow().isoformat()
        }
    )

# Log notification results
    async def _log_notification():
        print(f"Notified {len(notify_response)} waiting workflows")
        return notify_response

await context.run("log-notification", _log_notification)
```
</CodeGroup>

## External Notification

You can also notify workflows from external systems using the Workflow Client:

<CodeGroup>
```typescript TypeScript
import { Client } from "@upstash/workflow";

const client = new Client({ token: "<WORKFLOW_TOKEN>" });

await client.notify({
  eventId: "order-completed-123",
  eventData: {
    orderId: "123",
    status: "completed",
    deliveryTime: "2 days",
    trackingNumber: "TRK123456"
  }
});
```

```python Python
from upstash_workflow import Client

client = Client("<WORKFLOW_TOKEN>")

# Notify workflows waiting for a specific event
await client.notify(
    event_id="order-completed-123",
    event_data={
        "order_id": "123",
        "status": "completed",
        "delivery_time": "2 days",
        "tracking_number": "TRK123456"
    }
)
```
</CodeGroup>

## Lookback Functionality

By default, if you call `notify` before a workflow reaches its `waitForEvent` step, the notification will be lost (race condition). To prevent this, you can provide a `workflowRunId` parameter which enables **lookback** - the notification will be stored and delivered even if sent before the wait step.

This is particularly useful when:
* You trigger a workflow and immediately want to send it an event
* You have concurrent operations where timing is unpredictable
* You want to eliminate race conditions in your event-driven workflows

<CodeGroup>
```typescript TypeScript
import { Client } from "@upstash/workflow";

const client = new Client({ token: "<WORKFLOW_TOKEN>" });

// Trigger a workflow and get its run ID
const { workflowRunId } = await client.trigger({
  url: "https://your-app.com/api/process-order",
  body: { orderId: "123" }
});

// Immediately notify it with lookback enabled
// The notification will be delivered even if the workflow
// hasn't reached waitForEvent yet
await client.notify({
  eventId: "payment-verified",
  eventData: { verified: true, amount: 100 },
  workflowRunId: workflowRunId, // Enables lookback
});
```

```python Python
from upstash_workflow import Client

client = Client("<WORKFLOW_TOKEN>")

# Trigger a workflow and get its run ID
workflow_run = await client.trigger(
    url="https://your-app.com/api/process-order",
    body={"order_id": "123"}
)

# Immediately notify it with lookback enabled
await client.notify(
    event_id="payment-verified",
    event_data={"verified": True, "amount": 100},
    workflow_run_id=workflow_run.workflow_run_id  # Enables lookback
)
```
</CodeGroup>

The same also applies to `context.notify`

<CodeGroup>
```typescript TypeScript
import { serve } from "@upstash/workflow/nextjs";

export const { POST } = serve<string>(async (context) => {
  const { orderId, processingResult } = context.requestPayload;

await context.run("process-order", async () => {
    // ...
  })

});
```
</CodeGroup>

<Note>
When using lookback with `workflowRunId`, the notification is targeted to a specific workflow run rather than all waiters with that event ID.
</Note>

# Parallel Steps
Source: https://upstash.com/docs/workflow/features/parallel-steps

Upstash Workflow supports executing multiple steps in parallel.

Since each step returns a `Promise`, you can execute multiple steps concurrently by using `Promise.all()`.
This behavior works out of the box. No additional configuration is required.

```typescript app/api/workflow/route.ts
import { serve } from "@upstash/workflow/nextjs";
import { checkInventory, brewCoffee, printReceipt } from "@/utils";

export const { POST } = serve(async (context) => {

// 👇 Execute steps in parallel
  const [coffeeBeansAvailable, cupsAvailable, milkAvailable] =
    await Promise.all([
      context.run("check-coffee-beans", () => checkInventory("coffee-beans")),
      context.run("check-cups", () => checkInventory("cups")),
      context.run("check-milk", () => checkInventory("milk")),
    ]);

});
```

The results of the parallel steps are available as usual once awaited.

The dashboard visualizes parallel execution as shown below:

<img />

You can also await different step types together. For example, you can run a `context.call()` and a `context.run()` in parallel.

<Warning>
    Whether executing sequentially or in parallel, you should always
    <code>await</code> all promises in a workflow.
    Leaving promises unawaited may cause unexpected behavior.
</Warning>

# Overview
Source: https://upstash.com/docs/workflow/features/retries

Upstash Workflow provides an automatic retry mechanism to improve reliability and make workflows resilient against temporary failures.
Workflow automatically handles transient errors such as network issues or service unavailability.

## How Retries Work

When a step fails, Upstash Workflow automatically retries the failed step with configurable retry attempts and delay strategy.
This allows temporary issues to resolve without manual intervention.

<img />

By default, the retry count is set to **3**, and an **exponential backoff** delay strategy is used.

```javascript Default Backoff Algorithm
// n = how many times this request has been retried
delay = min(86400, e ** (2.5*n)) // in seconds
```

| Retry Attempt | Algorithm    | Delay  |
|---------------|--------------|--------|
| 1             | $$e^{2.5}$$  | 12s    |
| 2             | $$e^5$$      | 2m28s  |
| 3             | $$e^{7.5}$$  | 30m8s  |
| 4+            | $$86400$$    | 24h    |

## Configuration

You can configure retry behavior when starting a new workflow run.

### Configure Retry Attempt Count

You can specify how many times a step should be retried upon failure.

```typescript Configure Retry Attempt Count
import { Client } from "@upstash/workflow";

const client = new Client({ token: "<QSTASH_TOKEN>" })

const { workflowRunId } = await client.trigger({
  url: "https://<YOUR_WORKFLOW_ENDPOINT>/<YOUR-WORKFLOW-ROUTE>",
  retries: 3
})
```

### Configure Retry Delay Strategy

Retry delay is the time to wait before trying again after a failure. You can define a custom retry delay strategy.

The delay is defined as a math expression that is calculated on every retry.
The expression can use the `retried` variable, which represents how many times the step has already retried (starting from 0).

To apply a constant delay, you can simply provide a fixed value.

The expression must return the delay in **milliseconds**.

```typescript Configure Retry Delay Strategy
import { Client } from "@upstash/workflow";

const client = new Client({ token: "<QSTASH_TOKEN>" })

const { workflowRunId } = await client.trigger({
  url: "https://<YOUR_WORKFLOW_ENDPOINT>/<YOUR-WORKFLOW-ROUTE>",
  retries: 3,
  retryDelay: "(1 + retried) * 1000"
})
```

# Prevent Retries
Source: https://upstash.com/docs/workflow/features/retries/prevent-retries

It is recommended to enable retries for workflow runs to improve reliability.

However, in some cases, you may want to stop execution immediately when an error occurs, without causing additional retries.
Upstash Workflow provides several mechanisms to terminate workflow execution gracefully.

## Using `WorkflowNonRetryableError`

`WorkflowNonRetryableError` lets you explicitly fail a workflow without entering the retry cycle.

When thrown, the workflow run is marked as failed, which:
* Triggers the failure function (if defined)
* Sends the workflow run to the DLQ

```ts TypeScript highlight={7}
export const { POST } = serve<{ topic: string }>(async (context) => {
  const payload = context.requestPayload

const isExists = await context.run("is-user-exists", () => { ... });

if (!isExists) {
    throw new WorkflowNonRetryableError("The user does not exists!")
  }
})
```

## Using `context.cancel()`

You can cancel a workflow run explicitly from inside the workflow.

When canceled, the run is labeled as canceled instead of failed. This means:
* The failure handler will **NOT** be triggered
* The workflow will **NOT** be sent to the DLQ

<CodeGroup>
```typescript highlight={10-11} TypeScript
export const { POST } = serve<{ orderId: string }>(async (context) => {
  const { orderId } = context.requestPayload;

// Check if order is still valid
  const orderStatus = await context.run("check-order-status", async () => {
    return await getOrderStatus(orderId);
  });

if (orderStatus === "cancelled") {
    // Stop execution gracefully without error
    await context.cancel();
    return;
  }

// Continue processing if order is valid
  await context.run("process-order", async () => {
    return await processOrder(orderId);
  });
});
```

```python Python
@serve.post("/graceful-cancellation")
async def graceful_cancellation(context: AsyncWorkflowContext[dict]) -> None:
    order_id = context.request_payload["order_id"]

async def _check_order_status():
        return await get_order_status(order_id)

# Check if order is still valid
    order_status = await context.run("check-order-status", _check_order_status)

if order_status == "cancelled":
        # Stop execution gracefully without error
        await context.cancel()
        return

# Continue processing if order is valid
    async def _process_order():
        return await process_order(order_id)

await context.run("process-order", _process_order)
```
</CodeGroup>

## Using conditional execution

You can also use guard conditions to skip certain steps and exit early, without throwing errors or canceling the workflow.

In this case, the workflow run completes successfully because no error was raised.
<CodeGroup>
    ```typescript TypeScript highlight={10-11}
    export const { POST } = serve<{ data: any }>(async (context) => {
      const { data } = context.requestPayload;

// Check if order is still valid
      const orderStatus = await context.run("check-order-status", async () => {
        return await getOrderStatus(orderId);
      });

if (orderStatus === "not-found") {
        // Stop execution without error
        return;
      }

// Continue processing if order is valid
      await context.run("process-order", async () => {
        return await processOrder(orderId);
      });
    });
    ```

```python Python
    @serve.post("/conditional-execution")
    async def conditional_execution(context: AsyncWorkflowContext[dict]) -> None:
        data = context.request_payload["data"]

async def _validate_data():
            return validate_input_data(data)

# Validate data first
        validation_result = await context.run("validate-data", _validate_data)

if not validation_result["is_valid"]:
            # Log the validation failure
            async def _log_validation_failure():
                await log_validation_error(validation_result["errors"])

await context.run("log-validation-failure", _log_validation_failure)

# Stop execution without error
            return

# Only execute if validation passes
        async def _process_valid_data():
            return await process_data(data)

await context.run("process-valid-data", _process_valid_data)
    ```
</CodeGroup>

# Sleep
Source: https://upstash.com/docs/workflow/features/sleep

Upstash Workflow provides a **Sleep** feature that allows you to pause workflow execution for specified durations without consuming compute resources.

This feature enables you to build time-based workflows, implement delays between steps, and create scheduled operations without the limitations of traditional serverless timeouts.

## How Sleep Works

When you use `context.sleep` or `context.sleepUntil` in your workflow, Upstash Workflow automatically pauses execution and schedules the next step to run after the specified delay.
This happens without keeping your serverless function running, making it cost-effective and reliable for long delays.

<Note>
  **Important:** Sleep durations have limits based on your pricing plan:
  * **Free**: Maximum delay of 7 days
  * **Pay-as-you-go**: Maximum delay of 1 year
  * **Fixed pricing**: Custom delays (no limit)
</Note>

## Sleep Methods

Upstash Workflow provides two methods for implementing delays in your workflows:

### 1. context.sleep

Pauses workflow execution for a specified duration relative to the current time.

<CodeGroup>
```typescript TypeScript
import { serve } from "@upstash/workflow/nextjs";

export const { POST } = serve<string>(async (context) => {
  const { userId } = context.requestPayload;

// Send welcome email immediately
  await context.run("send-welcome-email", async () => {
    return await sendWelcomeEmail(userId);
  });

// Wait for 3 days before sending follow-up
  await context.sleep("wait-for-follow-up", "3d");

// Send follow-up email
  await context.run("send-follow-up-email", async () => {
    return await sendFollowUpEmail(userId);
  });
});
```

```python Python
from fastapi import FastAPI
from upstash_workflow.fastapi import Serve
from upstash_workflow import AsyncWorkflowContext

app = FastAPI()
serve = Serve(app)

@serve.post("/api/onboarding")
async def onboarding(context: AsyncWorkflowContext[str]) -> None:
    user_id = context.request_payload["user_id"]

# Send welcome email immediately
    async def _send_welcome_email():
        return await send_welcome_email(user_id)

await context.run("send-welcome-email", _send_welcome_email)

# Wait for 3 days before sending follow-up
    await context.sleep("wait-for-follow-up", "3d")

# Send follow-up email
    async def _send_follow_up_email():
        return await send_follow_up_email(user_id)

await context.run("send-follow-up-email", _send_follow_up_email)
```
</CodeGroup>

You can specify durations using human-readable strings:

* `"10s"` = 10 seconds
* `"1m"` = 1 minute
* `"30m"` = 30 minutes
* `"2h"` = 2 hours
* `"1d"` = 1 day
* `"1w"` = 1 week
* `"1mo"` = 1 month
* `"1y"` = 1 year

You can also use numeric values in seconds:

* `60` = 60 seconds (1 minute)
* `3600` = 3600 seconds (1 hour)
* `86400` = 86400 seconds (1 day)

### 2. context.sleepUntil

Pauses workflow execution until a specific timestamp in the future.

<CodeGroup>
```typescript TypeScript
import { serve } from "@upstash/workflow/nextjs";

export const { POST } = serve<string>(async (context) => {
  const { userId, scheduledTime } = context.requestPayload;

// Calculate the scheduled time
  const scheduledDate = new Date(scheduledTime);

// Wait until the scheduled time
  await context.sleepUntil("wait-until-scheduled", scheduledDate);

// Execute the scheduled task
  await context.run("execute-scheduled-task", async () => {
    return await executeTask(userId);
  });
});
```

```python Python
from fastapi import FastAPI
from upstash_workflow.fastapi import Serve
from upstash_workflow import AsyncWorkflowContext
from datetime import datetime

app = FastAPI()
serve = Serve(app)

@serve.post("/api/scheduled-task")
async def scheduled_task(context: AsyncWorkflowContext[str]) -> None:
    user_id = context.request_payload["user_id"]
    scheduled_time = context.request_payload["scheduled_time"]

# Calculate the scheduled time
    scheduled_date = datetime.fromisoformat(scheduled_time)

# Wait until the scheduled time
    await context.sleep_until("wait-until-scheduled", scheduled_date)

# Execute the scheduled task
    async def _execute_task():
        return await execute_task(user_id)

await context.run("execute-scheduled-task", _execute_task)
```
</CodeGroup>

For `context.sleepUntil`, you can use:

* `Date` objects (JavaScript/TypeScript)
* Unix timestamps (Python)
* ISO string dates

<Tip>
  Sleep operations have a precision of approximately 1 second. Very short delays (less than 1 second) may not be exact.
</Tip>

The sleep feature in Upstash Workflow provides a powerful way to create time-based, reliable workflows without the limitations of traditional serverless timeouts.

By leveraging this feature, you can build sophisticated business logic that spans hours, days, or even months while maintaining cost efficiency and reliability.

# Wait
Source: https://upstash.com/docs/workflow/features/wait

You can pause a workflow run with the `waitForEvent` step. An event is uniquely identified by event ID.

The workflow will resume when the matching event is published.

`waitForEvent` supports configurable timeouts to prevent workflows from waiting indefinitely.
When a timeout occurs, the returned object includes `timeout: true`, allowing you to handle the failure case gracefully (for example, cancel an order, notify the user, or retry later).

<Tip>
If no timeout is specified, the default is **7 days**.
</Tip>

<CodeGroup>
```typescript TypeScript
import { serve } from "@upstash/workflow/nextjs";

export const { POST } = serve<string>(async (context) => {
  const { orderId, userEmail } = context.requestPayload;

// Wait for order processing completion
  const { eventData, timeout } = await context.waitForEvent(
    "wait-for-order-processing",
    `order-${orderId}`,
    {
      timeout: "1d" // 1 day timeout
    }
  );

if (timeout) {
    // Handle timeout scenario
    await context.run("handle-timeout", async () => {
      return await handleOrderTimeout(orderId, userEmail);
    });
    return;
  }

});
```

```python Python
from fastapi import FastAPI
from upstash_workflow.fastapi import Serve
from upstash_workflow import AsyncWorkflowContext

app = FastAPI()
serve = Serve(app)

@serve.post("/api/order-processing")
async def order_processing(context: AsyncWorkflowContext[str]) -> None:
    order_id = context.request_payload["order_id"]
    user_email = context.request_payload["user_email"]

# Send order processing request
    async def _request_order_processing():
        return await request_order_processing(order_id)

await context.run("request-order-processing", _request_order_processing)

# Wait for order processing completion
    result = await context.wait_for_event(
        "wait-for-order-processing",
        f"order-{order_id}",
        timeout="10m"  # 10 minutes timeout
    )

if result["timeout"]:
        # Handle timeout scenario
        async def _handle_timeout():
            return await handle_order_timeout(order_id, user_email)

await context.run("handle-timeout", _handle_timeout)
        return

# Process the completed order
    async def _process_completed_order():
        return await process_completed_order(order_id, result["event_data"])

await context.run("process-completed-order", _process_completed_order)
```
</CodeGroup>

# Overview
Source: https://upstash.com/docs/workflow/features/wait-for-event

Wait for Event feature that allows you to pause workflow execution until an external event occurs.

This feature enables you to build asynchronous workflows that can wait for user interactions, external system responses, or any other events without consuming compute resources.

## How Wait for Event Works

When you use `context.waitForEvent()` in your workflow, Upstash Workflow automatically pauses execution and waits for an external notification to resume.
This happens without keeping your serverless function running, making it cost-effective and reliable for event-driven workflows.

Each waiter has a timeout duration to wait for the event and then fires automatically.

<Note>
   Wait for Event timeouts have limits based on your pricing plan:
  * **Free**: Maximum timeout of 7 days
  * **Pay-as-you-go**: Maximum timeout of 1 year
  * **Fixed pricing**: Custom timeouts (no limit)
</Note>

## Race Condition Between Wait and Notify

A race condition can occur when `notify` is called before `waitForEvent` is executed.
In this scenario, the notification will be sent but no workflow will be waiting to receive it, causing the event to be lost.

### Solutions

There are three ways to handle race conditions:

1. **Use lookback with `workflowRunId`** (Recommended for targeted notifications)
2. **Use [Webhooks](/docs/workflow/features/webhooks)** (Recommended for general use)
3. **Check and retry** (Manual approach)

#### Option 1: Lookback with workflowRunId

When you know which specific workflow run should receive the notification, you can provide a `workflowRunId` to enable lookback. The notification will be stored and delivered even if sent before `waitForEvent`:

<CodeGroup>
```typescript TypeScript
import { Client } from "@upstash/workflow";

const client = new Client({ token: "<WORKFLOW_TOKEN>" });

// Trigger a workflow
const { workflowRunId } = await client.trigger({
  url: "https://your-app.com/api/process-order",
  body: { orderId: "123" }
});

// Immediately notify with lookback - no race condition!
await client.notify({
  eventId: "payment-verified",
  eventData: { verified: true },
  workflowRunId: workflowRunId, // Enables lookback
});
```
</CodeGroup>

#### Option 2: Use Webhooks

[Webhooks](/docs/workflow/features/webhooks) have built-in lookback and are safer against timing issues for general event handling.

#### Option 3: Check and Retry

Alternatively, you can check the response of the `notify` operation and retry if needed:

<CodeGroup>
```typescript TypeScript
import { Client } from "@upstash/workflow";

const client = new Client({ token: "<WORKFLOW_TOKEN>" });

const result = await client.notify({
    eventId,
    eventData
});

// Check if any workflows were notified
if (result.waiters && result.waiters.length > 0) {
    console.log(`Notified ${result.waiters.length} workflows`);
    return result;
}

// If no workflows were waiting, wait and retry once
console.log("No workflows waiting, retrying in 5 seconds...");
await new Promise(resolve => setTimeout(resolve, 5000));

return await client.notify({
    eventId,
    eventData
});
```
</CodeGroup>

## Selecting an Event ID

When a workflow run waits on an event ID, it's appended to a list of waiters for the event ID.

When a notify request is sent, all workflow runs waiting for that event are notified sequentially.
To avoid heavy notify operations, it’s recommended to use unique event IDs instead of generic ones.
For example, instead of waiting on `user-sent-verification`, wait the workflow on `user-{userId}-sent-verification` event.

# Webhooks
Source: https://upstash.com/docs/workflow/features/webhooks

The Webhook feature allows you to pause workflow execution and wait for a webhook URL to be called, enabling seamless integration with third-party APIs and asynchronous operations.

This feature is perfect for scenarios where you need to:
* Wait for external API processing to complete
* Integrate with services that use callback URLs
* Receive notifications from external webhooks

## How Webhooks Work

When you use webhooks in your workflow, Upstash Workflow:

1. **Creates a unique webhook URL** via `context.createWebhook()`
2. **Provides the URL to external services** (typically through `context.call()`)
3. **Pauses execution** via `context.waitForWebhook()` until the webhook is called
4. **Resumes workflow** when the webhook receives a request or timeout is reached

This happens without keeping your serverless function running, making it cost-effective for long-running integrations.

## Examples

### Basic Usage

```typescript
import { serve } from "@upstash/workflow/nextjs";

export const { POST } = serve(async (context) => {
  // Step 1: Create webhook
  const webhook = await context.createWebhook("create webhook");

// Step 2: Call an external endpoint, which calls the webhookUrl upon completion
  const callResult = await context.call("call webhook caller", {
    url: "https://webhook/caller",
    method: "POST",
    body: JSON.stringify({
      webhookUrl: webhook.webhookUrl,
    }),
  });

// Step 3: Wait for the webhook to be called
  const webhookResponse = await context.waitForWebhook(
    "wait for webhook",
    webhook,
    "30s" // timeout
  );

if (webhookResponse.timeout) {
    console.log("Webhook was not called in time");
    // Handle timeout scenario
  } else {
    console.log("Webhook received:", webhookResponse.request);
    // Process the webhook data
  }
});
```

### Waiting for Multiple Calls

Some services send multiple progress updates to a webhook URL as processing continues. You can wait for the same webhook multiple times in a loop until you receive a final "finished" signal:

```typescript
while (true) {
  const webhookResponse = await context.waitForWebhook(
    `wait for progress update ${stepCount}`,
    webhook,
    "5m" // 5 minute timeout between updates
  );

if (webhookResponse.timeout) {
    console.log("No progress update received in time, exiting");
    break;
  } else {
    const request = webhookResponse.request;
    console.log("Progress update received:", await request.json());

if (request.headers.get("x-task-finished") === "true") {
      console.log("Task finished, exiting loop");
      break;
    }
  }
}
```

## Race Condition Safety

Webhooks have built-in **lookback** protection, making them safer against race conditions. If an external service calls the webhook URL before `context.waitForWebhook()` is executed, the webhook call is stored and will be returned when `waitForWebhook` is called.

This means you don't need to worry about timing issues between creating the webhook and waiting for it - the workflow will always receive the callback even if it arrives early.

## Comparison with Wait for Event

Webhooks and [Wait for Event](/docs/workflow/features/wait-for-event) serve similar purposes but with different approaches:

| Feature | Webhooks | Wait for Event |
|---------|----------|----------------|
| **Trigger** | External HTTP call to unique URL | Notify via Upstash Workflow Client |
| **Setup** | Create webhook, pass URL to external service | Share event ID with external service |
| **Integration** | Easy with callback-based APIs | Requires Workflow Client integration |
| **Lookback** | ✅ Yes - safe against race conditions | ❌ No - notify before wait will be lost |
| **Best For** | Third-party API callbacks | Internal event notifications |

Choose webhooks when integrating with external services that support callback URLs, or when you need protection against race conditions. Choose Wait for Event when you have control over the notification mechanism and can use the Workflow Client.

## API Reference

<CardGroup cols={2}>
  <Card title="context.createWebhook" icon="webhook" href="/workflow/basics/context/createWebhook">
    Create a unique webhook URL for external services to call
  </Card>
  <Card title="context.waitForWebhook" icon="clock" href="/workflow/basics/context/waitForWebhook">
    Wait for the webhook to be called or timeout
  </Card>
</CardGroup>

# Getting Started
Source: https://upstash.com/docs/workflow/getstarted

## Overview

Upstash Workflow lets you write **durable, reliable and performant serverless functions**. Get delivery guarantees, automatic retries on failure, scheduling and more without managing any infrastructure.

## Quickstarts

Upstash Workflow supports Next.js, Cloudflare Workers and [many other frameworks](/docs/workflow/quickstarts/platforms) in TypeScript and Python.

<CardGroup cols={2}>
  <Card
    title="Next.js"
    icon="node-js"
    href="/workflow/quickstarts/vercel-nextjs"
  >
    Build a Next.js application with QStash Workflow
  </Card>
  <Card
    title="Cloudflare Workers"
    icon="cloudflare"
    href="/workflow/quickstarts/cloudflare-workers"
  >
    Use and deploy Upstash Workflow on Cloudflare Workers
  </Card>
  <Card
    title="Next.js & FastAPI"
    icon="python"
    href="/workflow/quickstarts/nextjs-fastapi"
  >
    Use Upstash Workflow for Python with Next.js and FastAPI
  </Card>
</CardGroup>

## Key Features

<CardGroup cols={2}>
  <Card
    title="Failure Resilience"
    icon="shield"
  >
    If your platform experiences a temporary outage, your workflow can pick up right where it left off, ensuring stability even in unstable environments.
  </Card>
  <Card
    title="Long-Running Executions"
    icon="clock"
  >
    Run long-running REST endpoints, such as complex AI models or video processing tools, even on serverless platforms with strict time limits.
  </Card>
  <Card
    title="Events with Wait/Notify Mechanism"
    icon="bell"
    href="/workflow/features/wait-for-event"
  >
    Create workflows that wait for external events before proceeding. Ideal for user confirmations and asynchronous notifications.
  </Card>
  <Card
    title="Scheduled Jobs"
    icon="calendar"
    href="/workflow/howto/schedule"
  >
    Run jobs at regular intervals with support for cron expressions. Perfect for recurring tasks like reminders, reports, or newsletters.
  </Card>
  <Card
    title="Parallel Runs"
    icon="road"
    href="/workflow/features/parallel-steps"
  >
    Start independent tasks in parallel and wait for them to finish simultaneously, reducing latency.
  </Card>
  <Card
    title="Long Delays"
    icon="hourglass"
    href="/workflow/basics/context/sleep"
  >
    Need your code to “sleep” for days, weeks, or even months? Supports long delays beyond serverless time limits.
  </Card>
  <Card
    title="Delivery Guarantees"
    icon="rotate-right"
  >
    Ensures at-least-once delivery. Failed requests are logged in a Dead Letter Queue to prevent data loss.
  </Card>
  <Card
    title="Flow Control"
    icon="gauge"
    href="/workflow/features/flow-control"
  >
    Prevent overwhelming your app or external services by configuring rate per second or parallelism limits.
  </Card>
  <Card
    title="Observability"
    icon="eye"
    href="/workflow/basics/client/logs"
  >
    Monitor workflow steps with insights. Filter events to track successes, failures, retries, and stalls.
  </Card>
</CardGroup>

## Example Use Cases

Here are some example real world use-cases for Upstash Workflow:

<CardGroup cols={2}>
  <Card title="Agents" icon="robot" href="/workflow/agents/overview">
    Use LLM Agents equipped with custom tools to achieve tasks
  </Card>
  <Card title="AI Data Processing" icon="sparkles" href="/workflow/examples/allInOne">
    Download a large dataset without timeouts, process the data in chunks and generate a report.
  </Card>
  <Card
    title="Waiting For Events"
    icon="traffic-light"
    href="/workflow/examples/waitForEvent"
  >
    Control workflow execution with events, log event data and send emails
  </Card>
  <Card
    title="Authorization Webhook"
    icon="webhook"
    href="/workflow/examples/authWebhook"
  >
    Start a workflow from a webhook. Handle user creation, trial management,
    email reminders and notifications.
  </Card>
  <Card
    title="Customer Onboarding"
    icon="user"
    href="/workflow/examples/customerOnboarding"
  >
    Register a new user, send welcome emails, and periodically check and respond
    to the user's activity state with emails.
  </Card>
  <Card
    title="E-Commerce Order Fulfillment"
    icon="cart-flatbed-boxes"
    href="/workflow/examples/eCommerceOrderFulfillment"
  >
    Receive an order request, verify the stock, process the payment, and handle
    order dispatch and customer notifications.
  </Card>
  <Card
    title="Image Processing"
    icon="image"
    href="/workflow/examples/imageProcessing"
  >
    Manage uploading images to the data store. Apply filters and resize the
    images to different resolutions in parallel.
  </Card>
  <Card
    title="Retry Payments"
    icon="credit-card"
    href="/workflow/examples/paymentRetry"
  >
    Retry payments with a day of delay, send emails, and suspend account if
    payment fails after the retries.
  </Card>
</CardGroup>

## How it works

Upstash Workflow builds on the principle of steps. Instead of defining a single, complex piece of business logic, workflows contain multiple individual steps.

Each of the steps are executed by a separate request to your application, by preserving the output of previous steps.

In case of an error, a failed step is retried individually without needing to re-run any previous steps. Instead of the entire business logic, _each step_ can take up your serverless function execution duration, and many more benefits.

<img />

## Support

Need help or have questions? We're here to support you:

* Join our Discord community to ask questions and share feedback
* Open a ticket through the Intercom chatbox in the dashboard for any issue

# Cancel a Run
Source: https://upstash.com/docs/workflow/howto/cancel

You can cancel a running workflow both programatically and from your Upstash Workflow console.

## Cancelling via console

In your Upstash Workflow console, find the run you'd like to cancel and press the `Cancel Workflow` button on the right side:

<img />

## Cancelling programatically

```javascript
import { Client } from "@upstash/workflow";

const client = new Client({ token: "<QSTASH_TOKEN>" });
await client.cancel({ ids: "<WORKFLOW_RUN_ID>" });
```

And replace `<WORKFLOW_RUN_ID>` with your actual run ID. See [the documentation of `client.cancel` method for more information about other ways of canceling workflows](/docs/workflow/basics/client/cancel).

You can also use the [Upstash Workflow REST API](/docs/workflow/api-reference/runs/cancel-workflow-run) to cancel a run programatically.

# Update a Workflow
Source: https://upstash.com/docs/workflow/howto/changes

Workflows are composed of multiple steps. When you modify workflow code, it's important to consider how these changes might affect in-progress workflows.

## Issues

You cannot change the step order of an existing workflow.

If your code changes remove or reorder existing steps, in-progress workflows may attempt to continue from a point that no longer exists. This can lead to workflow failures, typically resulting in the following error:

```bash
HTTP status 400. Incompatible step name. Expected <STEP_NAME>, got <STEP_NAME>
```

## Safe changes

Updating workflow code is safe in the following cases:

* No active workflow runs exist
* Only new steps are added to the end of the workflow

## Guidelines for updating workflows

Consider the following approaches when updating your workflow code:

* **Accept potential failures:** If you're fine with in-progress workflows failing, you can make any code changes.
* **Use a different route:** To avoid failures, consider serving the updated workflow under a different route.
* **Stop traffic before deployment:** If you need to keep the same route, stop all traffic before deploying new code.
* **Add steps only:** If stopping traffic is not an option, limit your changes to adding new steps at the end of the workflow.

For a deeper understanding of these limitations, see our [how workflows work](/docs/workflow/basics/how) section.

# Configure a Run
Source: https://upstash.com/docs/workflow/howto/configure

You can configure a workflow run when starting it. The following are the options you can configure:

1. Retries: The number of retry attempt Upstash Workflow does when a step fails in the workflow run
2. Retry Delay: The delay strategy between retries when Upstash Workflow attempts retries.
3. Flow Control: The rate, period and parallelism that steps should respect and logical grouping key to share with other workflow runs.

You can pass these configuration options when starting a workflow run:

```typescript
import { Client } from "@upstash/workflow";

const client = Client()

const { workflowRunId } = await client.trigger({
    url: `http://localhost:3000/api/workflow`,
    retries: 3,
    retryDelay: "(1 + retries) * 1000",
    flowControl: {
        key: "limit-ads",
        rate: 1,
        parallelism: 10
    }
});
```

The workflow run configuration does **not** apply to `context.call()` and `context.invoke()` steps.
These steps accept their own configuration options, allowing fine-grained control over external requests.
If not specified, they fall back to their default values.

For details, see:
* [context.call](/docs/workflow/basics/context/run)
* [context.invoke](/docs/workflow/basics/context/run)

<Tip>
Upstash Workflow does not support step level configuration. The configuration applies to all steps executed by a workflow run.

If you want to specifically throttle a step, there is a workaround by splitting step to another workflow and using `context.invoke()`.
</Tip>

# Handle Failed Runs
Source: https://upstash.com/docs/workflow/howto/failures

This guide shows you how to **gracefully handle failed workflow runs**. This involves best practices on resolving runtime errors, logging and manually retrying runs that have failed multiple times.

## Why a workflow might fail

* A step in your workflow throws a database error that causes your code to fail at runtime.
* QStash calls your workflow URL, but the URL is not reachable - for example, because of a temporary outage of your deployment platform.
* A single step takes longer than your platform's function execution limit.

Workflow automatically retries a failed step based on your configuration (by default, it retries three times with exponential backoff).
This helps handle temporary outages or intermittent failures gracefully.

<img />

If, even after all retries, your step does not succeed, we'll move the failed run into your [Dead Letter Queue (DLQ)](/docs/qstash/howto/handling-failures#dead-letter-queue). That way, you can always manually retry it again and debug the issue.

<img />

If you want to take an action (a cleanup/log), you can configure either `failureFunction` or a `failureUrl` on the `serve` method of your workflow.
These options allow you to define custom logic or an external endpoint that will be triggered when a failure occurs.

## Using a `failureFunction` (recommended)

The `serve` function you use to create a workflow endpoint accepts a `failureFunction` parameter - an easy way to gracefully handle errors (i.e. logging them to Sentry) or your custom handling logic.

<CodeGroup>
```typescript TypeScript
export const { POST } = serve<string>(
  async (context) => {
    // Your workflow logic...
  },
  {
    failureFunction: async ({
      context,
      failStatus,
      failResponse,
      failHeaders,
    }) => {
      // Handle error, i.e. log to Sentry
      console.error("Workflow failed:", failResponse);

// You can optionally return a string that will be visible
      // in the UI (coming soon) and in workflow logs
      return `Workflow failed with status ${failStatus}: ${failResponse}`;
    },
  }
);
```

```python Python
async def failure_function(
    context,       # context during failure
    fail_status,   # failure status
    fail_response, # failure message
    fail_headers   # failure headers
):
    # handle the failure
    pass

@serve.post("/api/example", failure_function=failure_function)
async def example(context: AsyncWorkflowContext[str]) -> None: ...
```

</CodeGroup>

Note: If you use a custom authorization method to secure your workflow endpoint, add authorization to the `failureFunction` too. Otherwise, anyone can invoke your failure function. Read more here: [securing your workflow endpoint](/docs/workflow/howto/security).

In `@upstash/workflow`, the `failureFunction` can optionally return a string value that will be displayed in the UI (coming soon) and included in the workflow logs. This is useful for providing custom error messages, debugging information, or tracking specific failure conditions.

## Using a `failureUrl`

Instead of using the built-in failure function, you can define a separate failure callback URL.
Unlike the failure function, which only works when your application is running, the failure URL allows you to handle errors even if your application is completely down.
If the URL is a different service other than your application, it will be reachable in these cases.

By pointing the failure URL to an external service (not hosted within your main application), you ensure that it remains accessible even when your primary app is unavailable.

```typescript TypeScript
export const { POST } = serve<string>(
  async (context) => {
    // Your workflow logic...
  },
  {
    failureUrl: "https://<YOUR_FAILURE_URL>/workflow-failure",
  }
);
```

```python Python
@serve.post("/api/example", failureUrl="https://<YOUR-FAILURE-ENDPOINT>/...")
async def example(context: AsyncWorkflowContext[str]) -> None: ...
```

</CodeGroup>

The callback body sent to you will be a JSON object with the following fields:

```javascript JavaScript
{
  "status": 200,
  "header": { "key": ["value"] },         // Response header
  "body": "YmFzZTY0IGVuY29kZWQgcm9keQ==", // base64 encoded response body
  "retried": 2,                           // How many times we retried to deliver the original message
  "maxRetries": 3,                        // Number of retries before the message assumed to be failed to delivered.
  "sourceMessageId": "msg_xxx",           // The ID of the message that triggered the callback
  "topicName": "myTopic",                 // The name of the URL Group (topic) if the request was part of a URL Group
  "endpointName": "myEndpoint",           // The endpoint name if the endpoint is given a name within a topic
  "url": "http://myurl.com",              // The destination url of the message that triggered the callback
  "method": "GET",                        // The http method of the message that triggered the callback
  "sourceHeader": { "key": "value" },     // The http header of the message that triggered the callback
  "sourceBody": "YmFzZTY0kZWQgcm9keQ==",  // The base64 encoded body of the message that triggered the callback
  "notBefore": "1701198458025",           // The unix timestamp of the message that triggered the callback is/will be delivered in milliseconds
  "createdAt": "1701198447054",           // The unix timestamp of the message that triggered the callback is created in milliseconds
  "scheduleId": "scd_xxx",                // The scheduleId of the message if the message is triggered by a schedule
  "callerIP": "178.247.74.179"            // The IP address where the message that triggered the callback is published from
}
```

In Next.js you can use the following code to handle the callback:

```javascript JavaScript
// pages/api/callback.js

import { verifySignature } from "@upstash/qstash/nextjs";

function handler(req, res) {
  // responses from qstash are base64-encoded
  const decoded = atob(req.body.body);
  console.log(decoded);

return res.status(200).end();
}

export default verifySignature(handler);

export const config = {
  api: {
    bodyParser: false,
  },
};
```

`verifySignature` allows to verify the signature of request, which is signed by Upstash using your signing keys.
If you don't want to verify the signature, you can remove `QSTASH_CURRENT_SIGNING_KEY` and `QSTASH_NEXT_SIGNING_KEY` environment variables and remove `verifySignature` function.

## Manually Handling Failed Workflow Runs

When a workflow run fails and is moved to the Dead Letter Queue (DLQ), you have several options to handle it manually via the REST API:

### [Resume](/docs/workflow/api-reference/dlq/resume-workflow-from-dlq)
* **What it does:** Continues a failed workflow run from exactly where it failed, preserving all successful step results.
* **When to use:** Use this if you want to retry only the failed/pending steps without re-executing the entire workflow.

### [Restart](/docs/workflow/api-reference/dlq/restart-workflow-from-dlq)
* **What it does:** Starts the failed workflow run over from the beginning, discarding all previous step results.
* **When to use:** Use this if you want a clean execution, or if the failure may have been caused by a corrupted state that requires a fresh start.

### [Callback](/docs/workflow/api-reference/dlq/retry-failure-callback)
* **What it does:** Reruns the failure callback for a workflow run, in case the original failure callback was not delivered or failed.
* **When to use:** Use this to ensure your system is notified of workflow failures, even if the original callback attempt did not succeed.

## Debugging failed runs

In your DLQ, filter messages via the `Workflow URL` or `Workflow Run ID` to search for a particular failure. We include all request and response headers and bodies to simplify debugging failed runs.

For example, let's debug the following failed run. Judging by the status code `404`, the `Ngrok-Error-Code` header of `ERR_NGROK_3200` and the returned HTML body, we know that the URL our workflow called does not exist.

<img />

# Flow control
Source: https://upstash.com/docs/workflow/howto/flow-control

# Development Server
Source: https://upstash.com/docs/workflow/howto/local-development/development-server

Upstash Workflow is built on top of Upstash QStash.
The QStash CLI provides a local development server that performs QStash functionality locally for development and testing purposes.

## Automatic dev server (recommended)

If you are using `@upstash/workflow`, you can just set `QSTASH_DEV=true` in your environment, and the SDK will download and connect to the dev server automatically. No tokens or signing keys required.

```bash .env
QSTASH_DEV=true
```

With `QSTASH_DEV=true` set, both the workflow client and the `serve()` endpoint pick up the dev server automatically. The endpoint also verifies incoming signatures against the dev server's deterministic signing keys, so signature verification works end-to-end with no extra setup.

```typescript
// app/api/workflow/route.ts
import { serve } from "@upstash/workflow/nextjs";

export const { POST } = serve(async (context) => {
  await context.run("step-1", () => console.log("running locally"));
});
```

```typescript
import { Client } from "@upstash/workflow";

const client = new Client({ token: process.env.QSTASH_TOKEN ?? "" });

await client.trigger({
  url: "http://localhost:3000/api/workflow",
});
```

For details on the dev server behavior, ports, and the `registerQStashDev()` helper for Next.js edge routes, see the [QStash Local Development docs](/docs/qstash/howto/local-development).

## Manual setup

If you would rather start and manage the QStash dev server yourself, follow the steps below.

<Steps>
    <Step title="Install and Start Development Server">
        Start the development server using the QStash CLI:

```javascript
        npx @upstash/qstash-cli dev
        ```

The QStash CLI output will look something like this:

```plaintext QStash CLI Output
        Upstash QStash development server is runnning at

A default user has been created for you to authorize your requests.
        QSTASH_TOKEN=eyJVc2VySUQiOiJkZWZhdWx0VXNlciIsIlBhc3N3b3JkIjoiZGVmYXVsdFBhc3N3b3JkIn0=
        QSTASH_CURRENT_SIGNING_KEY=sig_7RvLjqfZBvP5KEUimQCE1pvpLuou
        QSTASH_NEXT_SIGNING_KEY=sig_7W3ZNbfKWk5NWwEs3U4ixuQ7fxwE

Sample cURL request:
        curl -X POST http://127.0.0.1:8080/v2/publish/https://example.com -H "Authorization: Bearer eyJVc2VySUQiOiJkZWZhdWx0VXNlciIsIlBhc3N3b3JkIjoiZGVmYXVsdFBhc3N3b3JkIn0="

Check out documentation for more details:
        https://upstash.com/docs/qstash/howto/local-development
        ```

For detailed instructions on setting up the development server, see our [QStash Local Development Guide](/docs/qstash/howto/local-development).
    </Step>

<Step title="Enable Local Mode on Console">
        Once you start the local server, you can go to the Workflow tab on Upstash Console and enable local mode, which will allow you to monitor and debug workflow runs with the local server.

<Step title="Update Environment Variables">
        Once your development server is running, update your environment variables to route QStash requests to your local server.

```env
        QSTASH_URL="http://127.0.0.1:8080"
        QSTASH_TOKEN="eyJVc2VySUQiOiJkZWZhdWx0VXNlciIsIlBhc3N3b3JkIjoiZGVmYXVsdFBhc3N3b3JkIn0="
        QSTASH_CURRENT_SIGNING_KEY="sig_7RvLjqfZBvP5KEUimQCE1pvpLuou"
        QSTASH_NEXT_SIGNING_KEY="sig_7W3ZNbfKWk5NWwEs3U4ixuQ7fxwE"
        ```

</Step>

<Step title="Use local addresses">
        It's all set up 🎉

Now, you can use your local address when triggering the workflow runs.

```javascript
        import { Client } from "@upstash/workflow";

const client = Client()

const { workflowRunId } = await client.trigger({
            url: `http://localhost:3000/api/workflow`,
            retries: 3
        });
        ```
        <Tip>
        Inside the `trigger()` call, you need to provide the URL of your workflow endpoint:

* Local development → use the URL where your app is running, for example: http://localhost:3000/api/PATH
        * Production → use the URL of your deployed app, for example: https://yourapp.com/api/PATH

To avoid hardcoding URLs, you can define a `BASE_URL` constant and set it based on the environment.
        A common pattern is to check an environment variable that only exists in production:

```javascript
        const BASE_URL = process.env.VERCEL_URL
          ? `https://${process.env.VERCEL_URL}`
          : `http://localhost:3000`

const { workflowRunId } = await client.trigger({
            url: `${BASE_URL}/api/workflow`,
            retries: 3
        });
        ```
        </Tip>

</Step>

</Steps>

# Local Tunnel
Source: https://upstash.com/docs/workflow/howto/local-development/local-tunnel

Upstash Workflow requires your application to be publicly accessible in production.
The recommended approach is running the development server we provide locally and work with local addresses.
An alternative is to making your application publibly accessible so that you can work with the managed Upstash Workflow servers.

The easiest way to make a local URL publically available is [ngrok](https://ngrok.com), a free tunneling service.

Create an account on [dashboard.ngrok.com/signup](https://dashboard.ngrok.com/signup) and follow the [setup instructions](https://dashboard.ngrok.com/get-started/setup) to download the ngrok CLI and connect your account. This process takes only a few minutes and is totally free.

You can connect your account like this:

Once you have installed the ngrok CLI, add your ngrok-issued auth token like this:

```bash Terminal
ngrok config add-authtoken <YOUR-AUTH-TOKEN>
```

and replace `<YOUR-AUTH-TOKEN>` with your actual auth token.

### Start the tunnel

Make your local server available publically by running the following command:

```bash
ngrok http <PORT>
```

for example, if your Next.js server is running on port `3000`, the command is:

```bash
ngrok http 3000
```

The output will look something like this:

```plaintext
Session Status                online
Account                       <YOUR-NAME> (Plan: Free)
Version                       3.1.0
Region                        Europe (eu)
Latency                       -
Web Interface                 http://127.0.0.1:4040
Forwarding                    https://e02f-2a02-810d-af40-5284-b139-58cc-89df-b740.eu.ngrok.io -> http://localhost:3000
Connections                   ttl     opn     rt1     rt5     p50     p90
                              0       0       0.00    0.00    0.00    0.00
```

The long URL in the `Forwarding` line serves the same purpose as your localhost URL, the only difference being that it is publically accessible. We need this URL to make our workflow available to QStash for local development, either as the `baseUrl` parameter or the `UPSTASH_WORKFLOW_URL` environment variable (both options provide the same functionality).

Note: The `UPSTASH_WORKFLOW_URL` environment variable is only necessary for local development. In production, the `baseUrl` parameter is automatically set and can be omitted.

<Tip>
  Ensure that the port of your local server matches the one you're using with ngrok. For example, if your server is
  running on port 8080, use `ngrok http 8080`.
</Tip>

# Middlewares
Source: https://upstash.com/docs/workflow/howto/middlewares

Middlewares allow you to intercept and respond to workflow lifecycle events and debug messages. They're useful for logging, monitoring, error tracking, and custom integrations.

## Overview

A middleware can hook into:
* **Lifecycle Events**: Run started, run completed, before/after step execution
* **Debug Events**: Errors, warnings, and info messages

## Built-in Middleware

Upstash Workflow provides a built-in logging middleware that you can use out of the box:

```typescript
import { serve } from "@upstash/workflow/nextjs";
import { loggingMiddleware } from "@upstash/workflow";

export const { POST } = serve(
  async (context) => {
    await context.run("step-1", () => {
      return "Hello World";
    });
  },
  {
    middlewares: [loggingMiddleware]
  }
);
```

The logging middleware outputs detailed execution logs to your application's console, including:
* When workflow runs start and complete
* Before and after each step execution
* Error, warning, and info messages

## Creating Custom Middleware

You can create your own middleware by instantiating a `WorkflowMiddleware` class.

### Using Direct Callbacks

The simplest way to create a middleware is by providing callbacks directly:

```typescript
import { WorkflowMiddleware } from "@upstash/workflow";

// Debug events
    onError: async ({ workflowRunId, error }) => {
      console.error(`Error in ${workflowRunId}:`, error);
    },
    onWarning: async ({ workflowRunId, warning }) => {
      console.warn(`Warning in ${workflowRunId}:`, warning);
    },
    onInfo: async ({ workflowRunId, info }) => {
      console.info(`Info from ${workflowRunId}:`, info);
    }
  }
});
```

### Using Init Function

For middlewares that need to initialize resources (like database connections or external clients), use the `init` pattern:

```typescript
import { WorkflowMiddleware } from "@upstash/workflow";

const databaseMiddleware = new WorkflowMiddleware({
  name: "database-logger",
  init: async () => {
    // Initialize your resources
    const db = await connectToDatabase();

// Return the callbacks that use the initialized resources
    return {
      runStarted: async ({ context }) => {
        await db.insert({ workflowRunId: context.workflowRunId, status: 'started' });
      },
      runCompleted: async ({ context, result }) => {
        await db.update({ workflowRunId: context.workflowRunId, status: 'completed', result });
      },
      onError: async ({ workflowRunId, error }) => {
        await db.insert({ workflowRunId, level: 'error', message: error.message });
      }
    };
  }
});
```

## Event Types

### Lifecycle Events

<ParamField path="runStarted" type="function">
  Called when a workflow run begins.

**Parameters:**
  * `context`: The workflow context

```typescript
  runStarted: async ({ context }) => {
    // Handle run start
  }
  ```
</ParamField>

<ParamField path="beforeExecution" type="function">
  Called before each step executes.

**Parameters:**
  * `context`: The workflow context
  * `stepName`: Name of the step about to execute

```typescript
  beforeExecution: async ({ context, stepName }) => {
    // Handle step start
  }
  ```
</ParamField>

<ParamField path="afterExecution" type="function">
  Called after each step completes.

**Parameters:**
  * `context`: The workflow context
  * `stepName`: Name of the completed step
  * `result`: The result returned by the step

```typescript
  afterExecution: async ({ context, stepName, result }) => {
    // Handle step completion
  }
  ```
</ParamField>

<ParamField path="runCompleted" type="function">
  Called when the entire workflow run finishes.

**Parameters:**
  * `context`: The workflow context
  * `result`: The final result of the workflow

```typescript
  runCompleted: async ({ context, result }) => {
    // Handle run completion
  }
  ```
</ParamField>

### Debug Events

<ParamField path="onError" type="function">
  Called when an error occurs.

**Parameters:**
  * `workflowRunId`: The workflow run ID (optional)
  * `error`: The error object

```typescript
  onError: async ({ workflowRunId, error }) => {
    // Handle error
  }
  ```
</ParamField>

<ParamField path="onWarning" type="function">
  Called when a warning is logged.

**Parameters:**
  * `workflowRunId`: The workflow run ID (optional)
  * `warning`: The warning message

```typescript
  onWarning: async ({ workflowRunId, warning }) => {
    // Handle warning
  }
  ```
</ParamField>

<ParamField path="onInfo" type="function">
  Called when an info message is logged.

**Parameters:**
  * `workflowRunId`: The workflow run ID (optional)
  * `info`: The info message

```typescript
  onInfo: async ({ workflowRunId, info }) => {
    // Handle info
  }
  ```
</ParamField>

## Examples

### Error Tracking Middleware

Send errors to an external monitoring service:

```typescript
import { WorkflowMiddleware } from "@upstash/workflow";

const errorTrackingMiddleware = new WorkflowMiddleware({
  name: "error-tracking",
  callbacks: {
    onError: async ({ workflowRunId, error }) => {
      await fetch("https://your-monitoring-service.com/errors", {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({
          workflowRunId,
          error: error.message,
          stack: error.stack,
          timestamp: new Date().toISOString()
        })
      });
    }
  }
});
```

### Multiple Middlewares

You can use multiple middlewares together:

```typescript
import { serve } from "@upstash/workflow/nextjs";
import { loggingMiddleware } from "@upstash/workflow";

export const { POST } = serve(
  async (context) => {
    // Your workflow logic
  },
  {
    middlewares: [
      loggingMiddleware,
      errorTrackingMiddleware,
      performanceMiddleware
    ]
  }
);
```

Middlewares are executed in the order they're provided in the array.

# Migration Guide
Source: https://upstash.com/docs/workflow/howto/migrations

This guide covers migration between different versions of Upstash Workflow.

<AccordionGroup>
  <Accordion title="January 2026 - Major Release 1.0.0" defaultOpen>
    In January 2026, we released 1.0.0 version of the TypeScript SDK with several breaking changes to improve the developer experience, reduce bundle size, and simplify configuration.

## Agents API → Separate Package

The Agents API has been moved to a separate package to remove the AI SDK dependency from the core workflow package.

### Migration Steps

1. Install the new package:

```bash
    npm install @upstash/workflow-agents
    ```

2. Update your imports:

```typescript
    // Old
    import { serve } from "@upstash/workflow/nextjs";

export const { POST } = serve(async (context) => {
      const model = context.agents.openai('gpt-3.5-turbo');
      const agent = context.agents.agent({ ... });
      const task = context.agents.task({ ... });
    });

// New
    import { serve } from "@upstash/workflow/nextjs";
    import { agentWorkflow } from "@upstash/workflow-agents";

export const { POST } = serve(async (context) => {
      const agents = agentWorkflow(context)

const model = agents.openai('gpt-3.5-turbo');
      const agent = agents.agent({ ... });
      const task = agents.task({ ... });
    });
    ```

See [Agents documentation](/docs/workflow/agents/overview) for more details.

## Removed `keepTriggerConfig` and `useFailureFunction`

These parameters are no longer needed in `client.trigger()` as both are now `true` by default.

### Migration Steps

Simply remove these parameters from your trigger calls:

```typescript
    // Old
    const { workflowRunId } = await client.trigger({
      url: "https://your-app.com/api/workflow",
      retries: 3,
      keepTriggerConfig: true,
      useFailureFunction: true
    });

// New
    const { workflowRunId } = await client.trigger({
      url: "https://your-app.com/api/workflow",
      retries: 3
    });
    ```

Configuration passed to `trigger()` now automatically applies to the entire workflow.

## Configuration Moved from `serve` to `trigger`

The `retries`, `flowControl`, `retryDelay`, and `failureUrl` options have been removed from `serve()` and should now be passed in `client.trigger()`.

### Migration Steps

Move configuration from serve options to trigger:

```typescript
    // Old
    export const { POST } = serve(
      async (context) => { ... },
      {
        retries: 3,
        retryDelay: "1000 * (1 + retried)",
        flowControl: { key: "my-key", rate: 10 }
      }
    );

// Trigger call
    await client.trigger({ url: "..." });

// New
    export const { POST } = serve(
      async (context) => { ... }
      // No configuration here anymore
    );

// Configuration in trigger call
    await client.trigger({
      url: "...",
      retries: 3,
      retryDelay: "1000 * (1 + retried)",
      flowControl: { key: "my-key", rate: 10 }
    });
    ```

This change makes it easier to configure different behavior for different workflow runs of the same endpoint.

<Note>
      In the Python SDK, these options remain in the `serve` decorator as they were before.
    </Note>

## Removed `stringifyBody` from `context.call` and `context.invoke`

The `stringifyBody` parameter has been removed. The `body` parameter now expects a string.

### Migration Steps

Update your call and invoke methods to use `JSON.stringify()`:

```typescript
    // Old
    const result = await context.call("call-api", {
      url: "https://api.example.com/endpoint",
      method: "POST",
      body: { key: "value" },
      stringifyBody: true
    });

// New
    const result = await context.call("call-api", {
      url: "https://api.example.com/endpoint",
      method: "POST",
      body: JSON.stringify({ key: "value" })
    });
    ```

The same applies to `context.invoke()`:

```typescript
    // Old
    await context.invoke("invoke-workflow", {
      workflow: otherWorkflow,
      body: { key: "value" },
      stringifyBody: true
    });

// New
    await context.invoke("invoke-workflow", {
      workflow: otherWorkflow,
      body: JSON.stringify({ key: "value" })
    });
    ```

## Logger → Middleware System

The logging system has been replaced with a more flexible middleware system.

### Migration Steps

Replace the old logger with the new middleware:

```typescript
    // Old
    // Logging was automatic or controlled via verbose option
    export const { POST } = serve(
      async (context) => { ... },
      { verbose: true }
    );

// New
    import { loggingMiddleware } from "@upstash/workflow";

export const { POST } = serve(
      async (context) => { ... },
      {
        middlewares: [loggingMiddleware]
      }
    );
    ```

You can also create custom middlewares for more control. See [Middlewares documentation](/docs/workflow/howto/middlewares) for details.

## Removed `onStepFinish`

The `onStepFinish` callback has been removed. Use middlewares instead.

### Migration Steps

Replace `onStepFinish` with a custom middleware:

```typescript
    // Old
    export const { POST } = serve(
      async (context) => { ... },
      {
        onStepFinish: (stepName, result) => {
          console.log(`Step ${stepName} finished with:`, result);
        }
      }
    );

// New
    import { WorkflowMiddleware } from "@upstash/workflow";

const stepFinishMiddleware = new WorkflowMiddleware({
      name: "step-finish",
      callbacks: {
        afterExecution: async ({ stepName, result }) => {
          console.log(`Step ${stepName} finished with:`, result);
        }
      }
    });

export const { POST } = serve(
      async (context) => { ... },
      {
        middlewares: [stepFinishMiddleware]
      }
    );
    ```

See [Middlewares documentation](/docs/workflow/howto/middlewares) for more details.

</Accordion>

<Accordion title="October 2024 - Migrate from @upstash/qstash">
    In October 2024, we released a new SDK, `@upstash/workflow`, for Upstash Workflow, separating its development from the QStash SDK. Although Upstash Workflow is built on QStash, our goal is to improve the developer experience and support with a dedicated SDK. Development for Upstash Workflow will occur in `@upstash/workflow`, and Workflow-related imports will be removed from `@upstash/qstash` in future releases.

If you started using Upstash Workflow with `@upstash/qstash`, you will need to migrate to `@upstash/workflow`. We have made some backward-incompatible changes, but we aim to make the transition as smooth as possible.
    In this guide, we will explain the changes you may need to make for migration.

### Install `@upstash/workflow`

First, we will need to install the new package with:

<Tabs>
      <Tab title="npm">
      ```bash
      npm install @upstash/workflow
      ```
      </Tab>
      <Tab title="pnpm">
      ```bash
      pnpm install @upstash/workflow
      ```
      </Tab>
      <Tab title="bun">
      ```bash
      bun add @upstash/workflow
      ```
      </Tab>
    </Tabs>

If you were using `@upstash/qstash` only for workflow, you can uninstall it from your project.

### Serve methods

You will need to change the imports from `@upstash/qstash` to @upstash/workflow:

```ts
    // old
    import { serve } from "@upstash/qstash/nextjs"

// new
    import { serve } from "@upstash/workflow/nextjs"
    ```

We have updated what our `serve` methods return. We made this change to make it
    easier to extend the API in the future.

For instance, Next.js method changed like this:

```javascript
    // old
    export const POST = serve(...);

// new
    export const { POST } = serve(...);
    ```

We kept the `serve` method of `Hono` the same. The rest are updated in a similar way.
    See [the quickstarts](/docs/workflow/quickstarts/platforms) for the new way `serve`
    should be used.

Additionally, `@upstash/workflow/nuxt` import is removed. You should use `@upstash/workflow/h3`
    instead. This change was made because `nuxt` uses `h3` under the hood and our `serve` method
    for `nuxt` can work with any project using `h3`.

### Updating `context.call`

If you were using [`context.call` method](/docs/workflow/basics/context#context-call) in your workflow, you will need to change
    how it's called and what it returns. Here is what the change looks like:

```javascript
    // old
    const result = await context.call("call step", "<call-url>", "POST", ...)

// new
    const {
      status,  // response status
      headers, // response headers
      body     // response body
    } = await context.call("call step", {
      url: "<call-url>",
      method: "POST",
      ...
    })
    ```

In the old version, we only returned the response body. Also, if the request
    to the url failed, [the workflow run would fail](/docs/workflow/howto/failures).

In the new version, we update how the parameters are passed to the `context.call`.
    Additionally, we change the fail behavior: if the request fails, it doesn't make the
    workflow fail. Instead, the status and the body is simply returned and workflow
    continues as usual.

If you have ongoing workflow runs which call `context.call` during your transition,
    `status` and `headers` fields may not be available in these old runs. After your
    transition, all workflow runs will have all three fields.

### Renaming Errors

The errors in Workflow were renamed from `QStashWorkflowError` and `QStashWorkflowAbort` to `WorkflowError` and `WorkflowAbort`.

</Accordion>
</AccordionGroup>

# Select a Region
Source: https://upstash.com/docs/workflow/howto/multi-region

## Overview

Upstash Workflow operates on top of QStash, which is available in two distinct regions: **EU region** and **US region**. Each region is completely independent with its own infrastructure, pricing, resources, and workflow runs.

## Regional URLs

* **EU Region**: `https://qstash-eu-central-1.upstash.io`, or `https://qstash.upstash.io`
* **US Region**: `https://qstash-us-east-1.upstash.io`

## Key Concepts

Each region maintains:
* Usage in each region is tracked and billed independently
* Workflow runs, events, and configurations are region-specific
* Each region has its own API tokens and signing keys

### Migration Between Regions

If you don't have any active resources (active workflow runs, schedules, url groups etc), you can simply update your environment variables with the new region to migrate. If you have active resources, you will need to migrate more gracefully, as described below.

You can migrate your Workflow resources from one region to another using the Upstash Console:

1. Navigate to the [Workflow tab on Upstash Console](https://console.upstash.com/workflow)
2. Click the **Migrate** button
3. Follow the guided migration process

<img />

The migration tool will:
* Help you set up migration-mode environment variables
* Copy and update your QStash resources (schedules, url groups, queues)

Your workflow logs or DLQ aren't part of the migration. They will remain in the old region.

<Info>
After migration, your app will be able to handle requests from both regions simultaneously to ensure a smooth transition.
</Info>

## Operating Modes

Workflow SDK supports two modes of operation:

### Single-Region Mode (Default)

When `QSTASH_REGION` environment variable is **not set**, the SDK operates in single-region mode:

* Uses `QSTASH_TOKEN` and `QSTASH_URL` (or defaults to EU region)
* All workflow triggers are sent through the configured region
* Incoming workflow requests are verified using default signing keys

```bash
# Single-region configuration (EU)
QSTASH_URL="https://qstash.upstash.io"
QSTASH_TOKEN="your_eu_token"
QSTASH_CURRENT_SIGNING_KEY="your_eu_current_key"
QSTASH_NEXT_SIGNING_KEY="your_eu_next_key"
```

### Migration Mode

When `QSTASH_REGION` is set to `US_EAST_1` or `EU_CENTRAL_1`, the SDK enables migration mode:

* Uses region-specific credentials for the primary region (`QSTASH_REGION`)
* Automatically handles region detection for incoming workflow requests
* Supports receiving workflow calls from multiple regions simultaneously

<Note>
  If a workflow run was started in one region, all its steps will execute in that region.
</Note>

Environment variables:

```bash
# Migration mode configuration with US as primary
QSTASH_REGION="US_EAST_1"

US_EAST_1_QSTASH_URL="https://qstash-us-east-1.upstash.io"
US_EAST_1_QSTASH_TOKEN="your_us_token"
US_EAST_1_QSTASH_CURRENT_SIGNING_KEY="your_us_current_key"
US_EAST_1_QSTASH_NEXT_SIGNING_KEY="your_us_next_key"

EU_CENTRAL_1_QSTASH_URL="https://qstash-eu-central-1.upstash.io"
EU_CENTRAL_1_QSTASH_TOKEN="your_eu_token"
EU_CENTRAL_1_QSTASH_CURRENT_SIGNING_KEY="your_eu_current_key"
EU_CENTRAL_1_QSTASH_NEXT_SIGNING_KEY="your_eu_next_key"
```

<Warning>
Migration mode relies on environment variables being available via `process.env`. It won't work on platforms where `process.env` is not available, such as Cloudflare Workers.
</Warning>

## SDK Requirements

Migration support requires:
* `@upstash/workflow` >= 1.1.0
* `@upstash/qstash` >= 2.9.0

Update your dependencies:

```bash
npm install @upstash/workflow@latest @upstash/qstash@latest
```

# Parallel Runs
Source: https://upstash.com/docs/workflow/howto/parallel-runs

Just like you can execute multiple JavaScript promises at the same time using `Promise.all`, you can run multiple workflow steps at the same time:

```typescript
const [result1, result2, result3] =
  await Promise.all([
    ctx.run("parallel-step-1", async () => { ... }),
    ctx.run("parallel-step-2", async () => { ... }),
    ctx.run("parallel-step-3", async () => { ... }),
  ])
```

In a complete code example, your workflow could look like this:

```typescript app/api/workflow/route.ts
import { serve } from "@upstash/workflow/nextjs";
import { checkInventory, brewCoffee, printReceipt } from "@/utils";

export const { POST } = serve(async (ctx) => {
  const [coffeeBeansAvailable, cupsAvailable, milkAvailable] =
    await Promise.all([
      ctx.run("check-coffee-beans", () => checkInventory("coffee-beans")),
      ctx.run("check-cups", () => checkInventory("cups")),
      ctx.run("check-milk", () => checkInventory("milk")),
    ]);

// If all ingedients available, brew coffee
  if (coffeeBeansAvailable && cupsAvailable && milkAvailable) {
    const price = await ctx.run("brew-coffee", async () => {
      return await brewCoffee({ style: "cappuccino" });
    });

await printReceipt(price);
  }
});
```

After running your workflow, your dashboard shows each step in detail:

<img />

# Realtime Quickstart
Source: https://upstash.com/docs/workflow/howto/realtime/basic

[**Upstash Realtime**](/docs/realtime/overall/quickstart) lets you emit events from your workflow and subscribe to them in real-time on your frontend.

## How It Works

Upstash Realtime is powered by Upstash Redis and provides a clean, 100% type-safe API for publishing and subscribing to events:

* Your frontend can subscribe to events
* When you **emit** an event, it's instantly delivered to live subscribers on the frontend
* You can also replay events that happened in the past

This guide shows you how to integrate Upstash Workflow with Upstash Realtime to display real-time progress updates in your frontend.

## Setup

### 1. Install Packages

```bash
npm install @upstash/workflow @upstash/realtime @upstash/redis zod
```

### 2. Configure Upstash Realtime

Create a Realtime instance in `lib/realtime.ts`:

```typescript title="lib/realtime.ts"
import { InferRealtimeEvents, Realtime } from "@upstash/realtime";
import { Redis } from "@upstash/redis";
import z from "zod/v4";

const redis = Redis.fromEnv();

const schema = {
  workflow: {
    runFinish: z.object({}),
    stepFinish: z.object({
      stepName: z.string(),
      result: z.unknown().optional(),
    }),
  },
};

export const realtime = new Realtime({ schema, redis });
export type RealtimeEvents = InferRealtimeEvents<typeof realtime>;
```

### 3. Create a Realtime Middleware

Create a custom middleware that will emit events to Realtime at `lib/middleware.ts`:

```typescript title="lib/middleware.ts"
import { WorkflowMiddleware } from "@upstash/workflow";
import { realtime } from "./realtime";

export const realtimeMiddleware = new WorkflowMiddleware({
  name: "realtime-events",
  callbacks: {
    afterExecution: async ({ context, stepName, result }) => {
      const channel = realtime.channel(context.workflowRunId);
      await channel.emit("workflow.stepFinish", {
        stepName,
        result,
      });
    },
    runCompleted: async ({ context }) => {
      const channel = realtime.channel(context.workflowRunId);
      await channel.emit("workflow.runFinish", {});
    },
  },
});
```

**Key points:**

* The `afterExecution` callback is triggered after each workflow step completes
* The `runCompleted` callback is triggered when the entire workflow finishes
* We use `context.workflowRunId` to create a unique channel for each workflow run
* Events are automatically emitted without needing to manually call emit inside your workflow steps

### 4. Create a Realtime Endpoint

Create an API route at `app/api/realtime/route.ts` to handle Realtime connections:

```typescript title="app/api/realtime/route.ts"
import { handle } from "@upstash/realtime";
import { realtime } from "@/lib/realtime";

export const GET = handle({ realtime });
```

This endpoint enables Server-Sent Events (SSE) connections for real-time updates.

### 5. Add the Realtime Provider

Wrap your application in the `RealtimeProvider` by updating your root layout at `app/layout.tsx`:

```tsx title="app/layout.tsx"
"use client";

import { RealtimeProvider } from "@upstash/realtime/client";

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html>
      <body>
        <RealtimeProvider>{children}</RealtimeProvider>
      </body>
    </html>
  );
}
```

### 6. Create a Typed Client Hook

Create a typed `useRealtime` hook at `lib/realtime-client.ts`:

```typescript title="lib/realtime-client.ts"
"use client";

import { createRealtime } from "@upstash/realtime/client";
import type { RealtimeEvents } from "./realtime";

export const { useRealtime } = createRealtime<RealtimeEvents>();
```

***

## Building the Workflow

### 1. Create the Workflow Endpoint

Create your workflow at `app/api/workflow/route.ts`:

```typescript title="app/api/workflow/route.ts"
import { serve } from "@upstash/workflow/nextjs";
import { realtimeMiddleware } from "@/lib/middleware";

type WorkflowPayload = {
  userId: string;
  action: string;
};

export const { POST } = serve<WorkflowPayload>(
  async (context) => {
    const { userId, action } = context.requestPayload;

await context.run("validate-data", async () => {
      return { valid: true, userId, action };
    });

await context.run("process-action", async () => {
      // Your business logic here
      return { processed: true, userId, action };
    });

return { success: true, workflowRunId: context.workflowRunId };
  },
  {
    middlewares: [realtimeMiddleware],
  }
);
```

**Key points:**

* Import the `realtimeMiddleware` from `@/lib/middleware`
* Pass the middleware in the `middlewares` array to the `serve` function
* The middleware automatically emits events after each step and when the workflow completes

### 2. Create a Trigger Endpoint

Create an endpoint to trigger workflows at `app/api/trigger/route.ts`:

```typescript title="app/api/trigger/route.ts"
import { NextRequest, NextResponse } from "next/server";
import { Client } from "@upstash/workflow";

export const workflowClient = new Client({
  token: process.env.QSTASH_TOKEN,
  baseUrl: process.env.QSTASH_URL,
});

export async function POST(request: NextRequest) {
  const workflowUrl = `${request.nextUrl.origin}/api/workflow`;

const { workflowRunId } = await workflowClient.trigger({
    url: workflowUrl,
    body: {
      userId: "user-123",
      action: "process-data",
    },
  });

return NextResponse.json({ workflowRunId });
}
```

***

## Building the Frontend

### 1. Create a Custom Hook

Create a React hook to manage the Realtime subscription at `hooks/useWorkflow.ts`:

```typescript
"use client";

import { useRealtime } from "@/lib/realtime-client";
import { useState, useCallback } from "react";

interface WorkflowStep {
  stepName: string;
  result?: unknown;
}

export function useWorkflow() {
  const [workflowRunId, setWorkflowRunId] = useState<string | null>(null);
  const [steps, setSteps] = useState<WorkflowStep[]>([]);
  const [isRunFinished, setIsRunFinished] = useState(false);

useRealtime({
    enabled: Boolean(workflowRunId),
    channels: workflowRunId ? [workflowRunId] : [],
    events: ["workflow.stepFinish", "workflow.runFinish"],
    onData({ event, data }) {
      if (event === "workflow.stepFinish") {
        setSteps((prev) => [...prev, data]);
      }

if (event === "workflow.runFinish") {
        setIsRunFinished(true);
      }
    },
  });

const trigger = () => {
    setSteps([]);
    setIsRunFinished(false);

const response = await fetch("/api/trigger", {
      method: "POST",
    });

const data = await response.json();
    setWorkflowRunId(data.workflowRunId);
  };

return {
    trigger,
    workflowRunId,
    steps,
    isRunFinished,
  };
}
```

**Key features:**

* Subscribe to multiple events using the `events` array: `["workflow.stepFinish", "workflow.runFinish"]`
* The hook manages both triggering the workflow and subscribing to updates
* Type-safe event handling with TypeScript

### 2. Use the Hook in Your Component

```tsx
"use client";

import { useWorkflow } from "@/hooks/useWorkflow";

export default function WorkflowPage() {
  const { trigger, steps, isRunFinished } = useWorkflow();

return (
    <div>
      <button onClick={trigger}>Click to Trigger Workflow</button>

{isRunFinished && <p>✅ Workflow Finished!</p>}

<p>Workflow Steps:</p>

{steps.map((step, index) => (
        <div key={index}>
          <strong>{step.stepName}</strong>
          {Boolean(step.result) && <span>: {JSON.stringify(step.result)}</span>}
        </div>
      ))}
    </div>
  );
}
```

## How It All Works Together

1. **User triggers workflow**: The frontend calls `/api/trigger`, which returns a `workflowRunId`
2. **Frontend subscribes**: Using the `workflowRunId`, the frontend subscribes to the Realtime channel
3. **Workflow executes**: The workflow runs as a background job, emitting events at each step
4. **Real-time updates**: As the workflow emits events, they're instantly delivered to the frontend via Server-Sent Events

## Full Example

For a complete working example with all steps, error handling, and UI components, check out the [Upstash Realtime example on GitHub](https://github.com/upstash/workflow-js/tree/main/examples/upstash-realtime).

## Next Steps

* Learn about [human-in-the-loop workflows with Realtime](./human-in-the-loop)
* Explore [Realtime features](/docs/realtime/overall/quickstart)
* Check out [Workflow configuration options](/docs/workflow/howto/configure)

# Human-in-the-Loop
Source: https://upstash.com/docs/workflow/howto/realtime/human-in-the-loop

Some workflows require human approval or input before proceeding. When combined with [**Upstash Realtime**](/docs/realtime/overall/quickstart), you can create interactive workflows that pause for user input and provide real-time feedback to your frontend during the entire process.

This guide shows you how to implement a human-in-the-loop workflow pattern with real-time updates using Upstash Workflow and Upstash Realtime.

## How It Works

In a human-in-the-loop workflow:

1. The workflow executes initial steps and emits progress events
2. The workflow pauses at a specific point using [`context.waitForEvent()`](/docs/workflow/features/wait-for-event)
3. A "waiting for input" event is emitted to notify the frontend
4. The user makes a decision in the frontend (approve/reject)
5. The frontend calls an API to notify the workflow using [`client.notify()`](/docs/workflow/basics/client/notify)
6. The workflow resumes with the user's decision
7. An "input resolved" event is emitted so the frontend can update its UI
8. The workflow continues and completes based on the decision

## Prerequisites

* An Upstash account with:
  * A QStash project for workflows
  * A Redis database for Realtime
* Next.js application set up
* Completed the [basic real-time workflow setup](./basic)

## Event Types

For human-in-the-loop workflows, extend your schema in `lib/realtime.ts` with these additional event types:

```typescript {8-14}
const schema = {
  workflow: {
    runFinish: z.object({}),
    stepFinish: z.object({
      stepName: z.string(),
      result: z.unknown().optional(),
    }),
    waitingForInput: z.object({
      eventId: z.string(),
      message: z.string(),
    }),
    inputResolved: z.object({
      eventId: z.string(),
    }),
  },
};
```

The new event types are:

* **`waitingForInput`**: Emitted when the workflow pauses and needs user input
* **`inputResolved`**: Emitted when the user provides input, so the frontend knows to clear the waiting state

## Create the Realtime Middleware

Create a custom middleware that will emit events to Realtime at `lib/middleware.ts`:

```typescript title="lib/middleware.ts"
import { WorkflowMiddleware } from "@upstash/workflow";
import { realtime } from "./realtime";

export const realtimeMiddleware = new WorkflowMiddleware({
  name: "realtime-events",
  callbacks: {
    beforeExecution: async ({ context, stepName }) => {
      const channel = realtime.channel(context.workflowRunId);

// Detect wait-for-event steps and emit waitingForInput
      if (stepName === "wait-for-approval") {
        await channel.emit("workflow.waitingForInput", {
          eventId: `approval-${context.workflowRunId}`,
          message: `Waiting for approval`,
        });
      }
    },
    afterExecution: async ({ context, stepName, result }) => {
      const channel = realtime.channel(context.workflowRunId);

// Emit inputResolved after wait-for-event steps complete
      if (stepName === "wait-for-approval") {
        await channel.emit("workflow.inputResolved", {
          eventId: `approval-${context.workflowRunId}`,
        });
      }

// Emit stepFinish for all steps
      await channel.emit("workflow.stepFinish", {
        stepName,
        result,
      });
    },
    runCompleted: async ({ context }) => {
      const channel = realtime.channel(context.workflowRunId);
      await channel.emit("workflow.runFinish", {});
    },
  },
});
```

**Key points:**

* The middleware handles all realtime event emissions automatically
* `beforeExecution`: Detects wait-for-event steps by checking the stepName and emits `workflow.waitingForInput`
* `afterExecution`: Emits `workflow.inputResolved` for wait steps and `workflow.stepFinish` for all steps
* `runCompleted`: Emits `workflow.runFinish` when the workflow finishes
* All emission logic is centralized in the middleware, keeping workflow code clean

## Building the Workflow

### 1. Create the Workflow Endpoint

Create your workflow at `app/api/workflow/human-in-loop/route.ts`:

```typescript title="app/api/workflow/human-in-loop/route.ts"
import { serve } from "@upstash/workflow/nextjs";
import { realtimeMiddleware } from "@/lib/middleware";

type WorkflowPayload = {
  userId: string;
  action: string;
};

export const { POST } = serve<WorkflowPayload>(
  async (context) => {
    const { userId, action } = context.requestPayload;

// Step 1: Initial Processing
    await context.run("initial-processing", async () => {
      // Your processing logic
      return {
        preprocessed: true,
        userId,
        action,
        requiresApproval: true,
      };
    });

// Step 2: Wait for Human Approval
    const eventId = `approval-${context.workflowRunId}`;

const { eventData, timeout } = await context.waitForEvent<{
      approved: boolean;
    }>("wait-for-approval", eventId, { timeout: "5m" });

// Handle timeout
    if (timeout) {
      return { success: false, reason: "timeout" };
    }

const status = eventData.approved ? "approved" : "rejected";

// Step 3: Process based on approval
    await context.run(`process-${status}`, async () => {
      return {
        status,
        processedAt: Date.now(),
        action,
        userId,
      };
    });

// Step 4: Finalize (only if approved)
    if (eventData.approved) {
      // Additional steps...
    }

return {
      success: true,
      approved: eventData.approved,
      workflowRunId: context.workflowRunId,
    };
  },
  {
    middlewares: [realtimeMiddleware],
  }
);
```

**Key patterns:**

1. **Middleware for all events**: The `realtimeMiddleware` automatically handles all realtime event emissions by detecting wait-for-event steps through the stepName
2. **Step name detection**: The middleware checks if `stepName === "wait-for-approval"` to know when to emit `waitingForInput` and `inputResolved` events
3. **Unique event IDs**: Use a unique `eventId` (like `approval-${workflowRunId}`) to identify which approval request this is
4. **Timeout handling**: Always handle the timeout case when waiting for events

### 2. Create the Notify Endpoint

Create an endpoint at `app/api/notify/route.ts` to handle user input:

```typescript
import { Client } from "@upstash/workflow";
import { NextRequest, NextResponse } from "next/server";

const workflowClient = new Client({
  baseUrl: process.env.QSTASH_URL!,
  token: process.env.QSTASH_TOKEN!,
});

export async function POST(request: NextRequest) {
  const body = await request.json();
  const { eventId, eventData } = body;

if (!eventId) {
    return NextResponse.json(
      { success: false, error: "eventId is required" },
      { status: 400 }
    );
  }

// Notify the workflow
  await workflowClient.notify({
    eventId,
    eventData,
  });

return NextResponse.json({ success: true });
}
```

<Note>
**Preventing Race Conditions**: If you need to trigger a workflow and immediately send it an event, you can use the `workflowRunId` parameter to enable lookback:

```typescript
await workflowClient.notify({
  eventId,
  eventData,
  workflowRunId: "wfr_abc123", // Ensures notification is delivered even if sent before waitForEvent
});
```

Learn more in the [notify documentation](/docs/workflow/basics/client/notify).
</Note>

## Building the Frontend

### 1. Extend the Custom Hook

Extend your hook from the basic example to handle waiting states:

```typescript
"use client";

import { useRealtime } from "@/lib/realtime-client";
import { useState, useCallback } from "react";

interface WorkflowStep {
  stepName: string;
  result?: unknown;
}

interface WaitingState {
  eventId: string;
  message: string;
}

export function useWorkflowWithRealtime() {
  const [workflowRunId, setWorkflowRunId] = useState<string | null>(null);
  const [steps, setSteps] = useState<WorkflowStep[]>([]);
  const [waitingState, setWaitingState] = useState<WaitingState | null>(null);
  const [isTriggering, setIsTriggering] = useState(false);
  const [isRunFinished, setIsRunFinished] = useState(false);

useRealtime({
    enabled: !!workflowRunId,
    channels: workflowRunId ? [workflowRunId] : [],
    events: [
      "workflow.stepFinish",
      "workflow.runFinish",
      "workflow.waitingForInput",
      "workflow.inputResolved",
    ],
    onData({ event, data }) {
      if (event === "workflow.stepFinish") {
        setSteps((prev) => [
          ...prev,
          {
            stepName: data.stepName,
            result: data.result,
          },
        ]);
      } else if (event === "workflow.runFinish") {
        setIsRunFinished(true);
      } else if (event === "workflow.inputResolved") {
        // Clear waiting state if it matches
        setWaitingState((prev) =>
          prev?.eventId === data.eventId ? null : prev
        );
      } else if (event === "workflow.waitingForInput") {
        setWaitingState({
          eventId: data.eventId,
          message: data.message,
        });
      }
    },
  });

const trigger = useCallback(async () => {
    setIsTriggering(true);
    setSteps([]);
    setWaitingState(null);
    setIsRunFinished(false);

const response = await fetch("/api/trigger", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({ workflowType: "human-in-loop" }),
    });

const data = await response.json();
    setWorkflowRunId(data.workflowRunId);
    setIsTriggering(false);
  }, []);

const continueWorkflow = useCallback(
    async (data: { approved: boolean }) => {
      if (!waitingState) {
        throw new Error("No workflow waiting for input");
      }

const response = await fetch("/api/notify", {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({
          eventId: waitingState.eventId,
          eventData: data,
        }),
      });

if (!response.ok) {
        throw new Error("Failed to notify workflow");
      }

// The waiting state will be cleared when we receive inputResolved event
    },
    [waitingState]
  );

return {
    trigger,
    continueWorkflow,
    isTriggering,
    workflowRunId,
    steps,
    waitingState,
    isRunFinished,
  };
}
```

**Key additions:**

* **`waitingState`**: Tracks when the workflow is waiting for input
* **`continueWorkflow`**: Function to submit user decisions back to the workflow
* **Multiple events subscription**: Uses `events` array to subscribe to multiple event types
* **Input resolved handling**: Clears the waiting state when the workflow receives the user's input

### 2. Use the Hook with Approval UI

```typescript
"use client";

import { useWorkflowWithRealtime } from "@/hooks/useWorkflowWithRealtime";

export default function WorkflowPage() {
  const {
    trigger,
    isTriggering,
    steps,
    isRunFinished,
    waitingState,
    continueWorkflow,
  } = useWorkflowWithRealtime();

return (
    <div
      style={{
        maxWidth: "600px",
        margin: "40px auto",
        fontFamily: "Arial, sans-serif",
      }}
    >
      <button onClick={trigger} disabled={isTriggering}>
        {isTriggering ? "Starting..." : "Click to Trigger Workflow"}
      </button>

{isRunFinished && (
        <h3 style={{ marginTop: "20px" }}>✅ Workflow Finished!</h3>
      )}

{/* Show workflow steps */}
      <h3 style={{ marginTop: "20px" }}>Workflow Steps:</h3>
      <div>
        {steps.map((step, index) => (
          <div key={index}>
            <strong>{step.stepName}</strong>
            {Boolean(step.result) && (
              <span>: {JSON.stringify(step.result)}</span>
            )}
          </div>
        ))}
      </div>

{/* Show approval UI when waiting for input */}
      {waitingState && (
        <div style={{ marginTop: "20px" }} className="approval-prompt">
          <p>{waitingState.message}</p>
          <p>
            <button onClick={() => continueWorkflow({ approved: true })}>
              Click to Approve
            </button>
          </p>
          <p>
            <button onClick={() => continueWorkflow({ approved: false })}>
              Click to Reject
            </button>
          </p>
        </div>
      )}
    </div>
  );
}
```

## How the Pattern Works

### Timeline of Events

1. **Initial processing**: `stepFinish` event → Frontend shows completed step
2. **Waiting for approval**: `waitingForInput` event → Frontend shows approval buttons
3. **User clicks approve/reject**: Frontend calls `/api/notify`
4. **Workflow resumes**: `inputResolved` event → Frontend hides approval buttons
5. **Processing continues**: More `stepFinish` events as workflow continues
6. **Workflow completes**: `runFinish` event → Frontend shows "Workflow Finished!"

## Benefits

* **Real-time feedback**: Users see exactly when their approval is needed
* **No polling**: Instant updates via Server-Sent Events
* **Timeout handling**: Workflows don't hang indefinitely waiting for input

## Full Example

For a complete working example with all steps, error handling, and full UI components, check out the [Upstash Realtime example on GitHub](https://github.com/upstash/workflow-js/tree/main/examples/upstash-realtime).

## Next Steps

* Review the [basic real-time workflow pattern](./basic)
* Learn about [workflow event handling](/docs/workflow/features/wait-for-event)
* Explore [Realtime features](/docs/realtime/overall/quickstart)
* Check out [workflow failure handling](/docs/workflow/features/failure-callback)

# Redact Private Data
Source: https://upstash.com/docs/workflow/howto/redact-fields

Workflow runs can contain private data that you don't want visible in the Upstash Console or API responses.

Upstash Workflow allows you to redact specific fields so they appear as `REDACTED:<SHA256>` in the dashboard and API. The original values are still used when delivering requests to your workflow endpoint. The SHA256 hash lets you verify the data without revealing the original values.

To redact fields, pass the `redact` option when triggering a workflow run.

<Info>
Redaction is one-way. Once a field is redacted, the original value cannot be retrieved from the API or dashboard.
</Info>

<CodeGroup>
```typescript TypeScript
import { Client } from "@upstash/workflow";

const client = new Client({ token: "<QSTASH_TOKEN>" });

const { workflowRunId } = await client.trigger({
  url: "https://my-app.com/api/workflow",
  body: { hello: "world" },
  redact: {
    body: true,
    header: ["Authorization"] // or `header: true` to redact all headers
  },
});
```

```python Python
from upstash_workflow import Client

client = Client("<QSTASH_TOKEN>")
client.trigger(
    url="https://my-app.com/api/workflow",
    body={
        "hello": "world",
    },
    redact={
        "body": True,
        "header": ["Authorization"] // or `header: True` to redact all headers
    },
)
```

```bash cURL
curl -XPOST \
    -H 'Authorization: Bearer XXX' \
    -H "Content-Type: application/json" \
    -H "Upstash-Redact-Fields: body, header[Authorization]" \
    -d '{ "hello": "world" }' \
    'https://qstash.upstash.io/v2/publish/https://my-app.com/api/workflow'
```
</CodeGroup>

<img />

Redaction is configured per workflow run, so you can redact different fields for different runs.

When `body` is redacted, the step outputs in the dashboard and API will show `REDACTED:<SHA256>` instead of the actual values. The workflow still executes with the original data.

If a workflow run fails and moves to the DLQ, the redacted fields remain redacted in the DLQ.
However, when you retry, resume or restart a workflow run from DLQ, Workflow delivers the original values to your endpoint.

# Schedule a Workflow
Source: https://upstash.com/docs/workflow/howto/schedule

You can schedule a workflow to run periodically using a cron definition.

For this feature, you would need to use Upstash QStash's Schedules feature.

## Scheduling a workflow

For example, let's suppose that you have a workflow that creates a backup of some important data daily. Our workflow endpoint might look like this:

To run this endpoint on a schedule, navigate to `Schedules` in your QStash dashboard and click `Create Schedule`:

<img />

Enter your live endpoint URL, add a CRON expression to define the interval at which your endpoint is called (i.e. every day, every 15 minutes, ...) and click `Schedule`:

<img />

Your workflow will now run repeatedly at the interval you have defined. For more details on CRON expressions, see our [QStash scheduling documentation](/docs/qstash/features/schedules).

## Programmatically Schedule

In order to massively improve the user experience, many applications send weekly summary reports to their users. These could be weekly analytics summaries or SEO statistics to keep users engaged with the platform.

Let's create a user-specific schedule, sending a first report to each user exactly 7 days after they signed up:

```typescript api/sign-up/route.ts
import { signUp } from "@/utils/auth-utils";
import { Client } from "@upstash/qstash";

const client = new Client({ token: process.env.QSTASH_TOKEN! });

export async function POST(request: Request) {
  const userData: UserData = await request.json();

// Schedule weekly account summary
  await client.schedules.create({
    scheduleId: `user-summary-${user.email}`,
    destination: "https://<YOUR_APP_URL>/api/send-weekly-summary",
    body: { userId: user.id },
    cron: cron,
  });

return NextResponse.json(
    { success: true, message: "User registered and summary scheduled" },
    { status: 201 }
  );
}
```

```python main.py
from fastapi import FastAPI, Request
from fastapi.responses import JSONResponse
from qstash import AsyncQStash
from datetime import datetime, timedelta

app = FastAPI()

client = AsyncQStash("<QSTACK_TOKEN>")

@app.post("/api/sign-up")
async def sign_up(request: Request):
    user_data = await request.json()

# Simulate user registration
    user = await sign_up(user_data)

# Calculate the date for the first summary (7 days from now)
    first_summary_date = datetime.now() + timedelta(days=7)

# Create cron expression for weekly summaries starting 7 days from signup
    cron = f"{first_summary_date.minute} {first_summary_date.hour} * * {first_summary_date.day}"

# Schedule weekly account summary
    await client.schedule.create_json(
        schedule_id=f"user-summary-{user.email}",
        destination="https://<YOUR_APP_URL>/api/send-weekly-summary",
        body={"userId": user.id},
        cron=cron,
    )

return JSONResponse(
        content={"success": True, "message": "User registered and summary scheduled"},
        status_code=201,
    )

```

</CodeGroup>

This code will call our workflow every week, starting exactly seven days after a user signs up. Each call to our workflow will contain the respective user's ID.

<Note>
    When creating a per-user schedule, pass a unique `scheduleId` to identify the schedule for better management and observability.
</Note>

# Secure a Workflow
Source: https://upstash.com/docs/workflow/howto/security

To prevent unauthorized access to your workflow endpoint, you can add an authorization layer.
Upstash Workflow supports two approaches:

* **Built-in request verification** (recommended)
* **Custom authorization method**

### Built-in request verification (recommended)

Upstash Workflow provides a built-in mechanism to secure your workflow endpoint by verifying request signatures.
Every request to your endpoint include a valid `Upstash-Signature` header.

How it works:

1. Upstash Workflow automatically adds the `Upstash-Signature` header to every request.
   This signature is generated using your signing keys.

2. When this mechanism is enabled, the SDK verifies that the signature is valid before processing the request.

This ensures that only requests originating from Upstash Workflow are processed.

To enable this verification, set the following environment variables in your application:

```bash .env
QSTASH_CURRENT_SIGNING_KEY=xxxxxxxxx
QSTASH_NEXT_SIGNING_KEY=xxxxxxxxx
```

You can find the values in Upstash Workflow dashboard.

<img />

<Info>
    For edge cases where environment variables cannot be used, you can explicitly create and pass a `Receiver` object to verify request signatures:

```typescript TypeScript
        import { Receiver } from "@upstash/qstash";
        import { serve } from "@upstash/workflow/nextjs";

export const { POST } = serve(
          async (context) => { ... },
          {
            receiver: new Receiver({
              currentSigningKey: "<QSTASH_CURRENT_SIGNING_KEY>",
              nextSigningKey: "<QSTASH_NEXT_SIGNING_KEY>",
            }),
          }
        );
        ```

```python Python
        from qstash import Receiver

```
    </CodeGroup>
</Info>

## Custom Authorization Method

You can implement your own authorization mechanism with Upstash Workflow.

The context object provides access to the initial request headers and payload on every workflow step.
You can use them to pass your custom authentication token to verify the requests.

```typescript TypeScript
    import { serve } from "@upstash/workflow/nextjs";

export const { POST } = serve(
      async (context) => {
        // 👇 Extract Bearer token form the request headers
        const authHeader = context.headers.get("authorization");
        const bearerToken = authHeader?.split(" ")[1];

// 👇 Use your authentication function to verify the token
        if (!isValid(bearerToken)) {
          console.error("Authentication failed.");
          return;
        }

// Your workflow steps..
      },
      {
        failureFunction: async () => {
          // 👇 Same auth check for failure function
          const authHeader = context.headers.get("authorization");
          const bearerToken = authHeader?.split(" ")[1];

if (!isValid(bearerToken)) {
            // ...
          }
        },
      }
    );
    ```

```python Python
    from fastapi import FastAPI
    from upstash_workflow.fastapi import Serve
    from upstash_workflow import AsyncWorkflowContext

app = FastAPI()
    serve = Serve(app)

@serve.post("/api/example")
    async def example(context: AsyncWorkflowContext[str]) -> None:
        auth_header = context.headers.get("authorization")
        bearer_token = auth_header.split(" ")[1] if auth_header else None

if not is_valid(bearer_token):
            print("Authentication failed.")
            return

# Your workflow steps...

```

</CodeGroup>

<Warning>
    If you implement custom authorization in your workflow route, you should also include the same authorization check in the failure function.

The failure function executes independently of the route function, so without this check, unauthorized requests could trigger the failure function
</Warning>

# Start a Run
Source: https://upstash.com/docs/workflow/howto/start

You’ve defined your workflow, and the final step is to trigger the endpoint!

There are two main ways to start your workflow:

### Using `client.trigger` (Recommended)

We recommend using [`client.trigger`](/docs/workflow/basics/client/trigger) to start your workflow.

<CodeGroup>
    ```ts Single Workflow
    import { Client } from "@upstash/workflow";

const client = new Client({ token: "<QSTASH_TOKEN>" })
    const { workflowRunId } = await client.trigger({
      url: "https://<YOUR_WORKFLOW_ENDPOINT>/<YOUR-WORKFLOW-ROUTE>",
      body: "hello there!",         // optional body
      headers: { ... },             // optional headers
      workflowRunId: "my-workflow", // optional workflow run id
      retries: 3                    // optional retries in the initial request
      delay: "10s"                  // optional delay value
      failureUrl: "https://<YOUR_FAILURE_URL>", // optional failure url
      flowControl: { ... }          // optional flow control
    })

console.log(workflowRunId)
    // prints wfr_my-workflow
    ```

```ts Multiple Workflows
    import { Client } from "@upstash/workflow";

const client = new Client({ token: "<QSTASH_TOKEN>" })
    const results = await client.trigger([
      {
        url: "<YOUR_WORKFLOW_ENDPOINT>",
        // other options...
      },
      {
        url: "<YOUR_WORKFLOW_ENDPOINT>",
        // other options...
      },
    ])

console.log(results[0].workflowRunId)
    // prints wfr_my-workflow
    ```
</CodeGroup>

### 2. Sending an HTTP Request

This approach is recommended for quick testing via curl during development.

You should **NOT** start the workflow run in production by direct calls to your endpoint.

```bash
curl -X POST https://<YOUR_WORKFLOW_ENDPOINT>/<YOUR-WORKFLOW-ROUTE> \
   -H "my-header: foo" \
   -d '{"foo": "bar"}'
```

<Warning>
    If you’ve secured your endpoint with signing keys, only the `trigger` method will work. Direct calls to the endpoint (e.g., via `curl` or `fetch`) will not be possible since `Upstash-Signature` header is missing.

For more information, read [Secure a workflow](/docs/workflow/howto/security) documentation.
</Warning>

# Webhooks
Source: https://upstash.com/docs/workflow/howto/use-webhooks

This guide explains how to handle webhooks effectively in your Upstash Workflow applications. We'll walk through:

* setting up webhook endpoints
* verifying webhook requests
* and processing webhook events

<Card
  title="GitHub Repository"
  icon="github"
  href="https://github.com/upstash/workflow-js/tree/main/examples/nextjs-webhook-stripe"
  horizontal
>
  You can find the project source code on GitHub.
</Card>

## Overview

Webhooks allow external services to notify your application when events occur. For example, you can use webhooks to receive notifications when a new order is placed in your e-commerce store, a new user signs up, or a new message is sent in your chat application.

Upstash Workflow provides a simple way to receive these events and trigger workflows based on the incoming data autonomously.

### Setting Up Webhook Endpoints

#### Basic Setup

To create a webhook endpoint, use the `serve` function from `@upstash/workflow`:

```typescript TypeScript
import { serve } from "@upstash/workflow/nextjs";

export const { POST } = serve(
  async (context) => {
    // Your webhook handling logic here
  },
  {
    initialPayloadParser: (payload) => {
      return payload;
    },
  }
);
```

```python Python
from fastapi import FastAPI
from upstash_workflow.fastapi import Serve
from upstash_workflow import AsyncWorkflowContext

app = FastAPI()
serve = Serve(app)

def initial_payload_parser(payload):
    return payload

@serve.post("/api/example", initial_payload_parser=initial_payload_parser)
async def example(context: AsyncWorkflowContext[str]) -> None:
    # Your webhook handling logic here

```

</CodeGroup>

#### Request Validation

Always validate incoming webhook requests to ensure they're legitimate. This way, no one other than the original webhook source can trigger your workflow. Here's an example using Clerk webhooks with Svix:

<CodeGroup>
```typescript Validate and Parse in Workflow - TypeScript
export const { POST } = serve<string>(async (context) => {
	const payloadString = context.requestPayload;
	const headerPayload = context.headers;

let event: WebhookEvent;
    try {
    	event = await validateRequest(payloadString, headerPayload);
    } catch {
    	return
    }

// Next steps based on the event

})

```

```python Validate and Parse in Workflow - Python
async def validate_request(payload_string: str, header_payload: dict):
    # Validate the request
    pass

@serve.post("/api/example")
async def example(context: AsyncWorkflowContext[str]) -> None:
    payload_string = context.request_payload
    header_payload = context.headers

try:
        event = await validate_request(payload_string, header_payload)
    except:
        return

# Next steps based on the event

```

```typescript Validation Function - TypeScript
import { Webhook } from "svix";
import { WebhookEvent } from "@clerk/nextjs/server";

const webhookSecret = "YOUR_WEBHOOK_SECRET";

async function validateRequest(payloadString: string, headerPayload: Headers) {
  const svixHeaders = {
    "svix-id": headerPayload.get("svix-id") as string,
    "svix-timestamp": headerPayload.get("svix-timestamp") as string,
    "svix-signature": headerPayload.get("svix-signature") as string,
  };
  const wh = new Webhook(webhookSecret);
  return wh.verify(payloadString, svixHeaders) as WebhookEvent;
}
```

</CodeGroup>

### Handling Webhook events

Use the context.run method to process webhook events in discrete, trackable steps:

```typescript TypeScript
export const { POST } = serve(async (context) => {
  // ... Parse and validate the incoming request

const user = await context.run<false | UserPayload>(
    "handle-webhook-event",
    async () => {
      if (event.type === "user.created") {
        const { id: clerkUserId, email_addresses, first_name } = event.data;
        const primaryEmail = email_addresses.find(
          (email) => (email.id = event.data.primary_email_address_id)
        );

if (!primaryEmail) {
          return false;
        }

return {
          event: event.type,
          userId: clerkUserId,
          email: primaryEmail.email_address,
          firstName: first_name,
        } as UserPayload;
      }
      return false;
    }
  );
});
```

```python Python
@serve.post("/api/example")
async def example(context: AsyncWorkflowContext[str]) -> None:
    # ... Parse and validate the incoming request

async def _handle_webhook_event():
        if event.type == "user.created":
            clerk_user_id = event.data["id"]
            email_addresses = event.data["email_addresses"]
            first_name = event.data["first_name"]

primary_email = next(
                (
                    email
                    for email in email_addresses
                    if email.id == event.data["primary_email_address_id"]
                ),
                None,
            )

if not primary_email:
                return False

return {
                "event": event.type,
                "user_id": clerk_user_id,
                "email": primary_email["email_address"],
                "first_name": first_name,
            }

return False

user = await context.run("handle-webhook-event", _handle_webhook_event)

```

</CodeGroup>

After validating the webhook and extracting the initial user data, you'll often need to perform additional operations like creating customer records, sending welcome emails etc.

```typescript TypeScript
export const { POST } = serve(async (context) => {
  // ... Previous validation and user data extraction

if (!user) {
    return;
  }

const customer = await context.run("create-stripe-customer", async () => {
    return await stripe.customers.create({
      email: user.email,
      name: `${user.firstName} ${user.lastName}`,
      metadata: {
        userId: user.userId,
      },
    });
  });

/// ... Additional steps
});
```

```python Python
@serve.post("/api/example")
async def example(context: AsyncWorkflowContext[str]) -> None:
    # ... Previous validation and user data extraction

if not user:
        return

async def _create_stripe_customer():
        return await stripe.customers.create(
            email=user["email"],
            name=f"{user['first_name']} {user['last_name']}",
            metadata={"user_id": user["user_id"]},
        )

customer = await context.run("create-stripe-customer", _create_stripe_customer)

# ... Additional steps

```

</CodeGroup>

You're now ready to perform any operation in the following steps.

# Vercel AI SDK
Source: https://upstash.com/docs/workflow/integrations/aisdk

<Card title="GitHub Repository" icon="github" href="https://github.com/upstash/workflow-js/blob/main/examples/nextjs/app/vercel-ai-sdk/route.ts" horizontal>
  You can find the project source code which uses real APIs on Github.
</Card>

Upstash Workflow integrates with the Vercel AI SDK to provide durable and reliable AI applications. This allows you to:

* Build resilient AI applications with automatic retries
* Manage AI operations with workflow steps
* Implement tools and function calling with durability
* Handle errors gracefully across your AI operations
* Handle long-running AI operations with extended timeouts

This guide will walk you through setting up and implementing AI features using Upstash Workflow's durability guarantees with Vercel AI SDK's capabilities.

## Prerequisites

Before getting started, make sure you have:

* An OpenAI API key
* Basic familiarity with Upstash Workflow and Vercel AI SDK
* Vercel AI SDK version 4.0.12 or higher (required for ToolExecutionError handling)

## Installation

Install the required packages:

<CodeGroup>
```bash npm
npm install @ai-sdk/openai ai zod
```

```bash pnpm
pnpm install @ai-sdk/openai ai zod
```

```bash bun
bun install @ai-sdk/openai ai zod
```

</CodeGroup>

## Implementation

### Creating OpenAI client

AI SDKs (Vercel AI SDK, OpenAI SDK etc.) uses the client's default fetch implementation to make API requests, but allows you to provide a custom fetch implementation.

In the case of Upstash Workflow, we need to use the `context.call` method to make HTTP requests. We can create a custom fetch implementation that uses `context.call` to make requests. By using `context.call`, Upstash Workflow is the one making the HTTP request and waiting for the response, even if it takes too long to receive response from the LLM.

The following code snippet can also be generalized to work with other LLM SDKs, such as Anthropic or Google.

```typescript {18-24}
import { createOpenAI } from '@ai-sdk/openai';
import { HTTPMethods } from '@upstash/qstash';
import { WorkflowAbort, WorkflowContext } from '@upstash/workflow';

export const createWorkflowOpenAI = (context: WorkflowContext) => {
  return createOpenAI({
    compatibility: "strict",
    fetch: async (input, init) => {
      try {
        // Prepare headers from init.headers
        const headers = init?.headers
          ? Object.fromEntries(new Headers(init.headers).entries())
          : {};

// Prepare body from init.body
        const body = init?.body ? JSON.parse(init.body as string) : undefined;

// Make network call
        const responseInfo = await context.call("openai-call-step", {
          url: input.toString(),
          method: init?.method as HTTPMethods,
          headers,
          body,
        });

// Construct headers for the response
        const responseHeaders = new Headers(
          Object.entries(responseInfo.header).reduce((acc, [key, values]) => {
            acc[key] = values.join(", ");
            return acc;
          }, {} as Record<string, string>)
        );

// Return the constructed response
        return new Response(JSON.stringify(responseInfo.body), {
          status: responseInfo.status,
          headers: responseHeaders,
        });
      } catch (error) {
        if (error instanceof WorkflowAbort) {
          throw error
        } else {
          console.error("Error in fetch implementation:", error);
          throw error; // Rethrow error for further handling
        }
      }
    },
  });
};
```

### Using OpenAI client to generate text

Now that we've created the OpenAI client, we can use it to generate the text.

For that, we're going to create a new workflow endpoint that uses the payload as prompt to generate text using the OpenAI client.

```typescript {8, 16-20}
import { serve } from "@upstash/workflow/nextjs";
import { WorkflowAbort } from '@upstash/workflow';
import { generateText, ToolExecutionError } from 'ai';

import { createWorkflowOpenAI } from './model';

export const { POST } = serve<{ prompt: string }>(async (context) => {
  const openai = createWorkflowOpenAI(context);

// Important: Must have a step before generateText
  const prompt = await context.run("get prompt", async () => {
    return context.requestPayload.prompt;
  });

try {
    const result = await generateText({
      model: openai('gpt-3.5-turbo'),
      maxTokens: 2048,
      prompt,
    });

await context.run("text", () => {
      console.log(`TEXT: ${result.text}`);
      return result.text;
    });

} catch (error) {
    if (error instanceof ToolExecutionError && error.cause instanceof WorkflowAbort) {
      throw error.cause;
    } else {
      throw error;
    }
  }
});
```

We can either [run the app locally](/docs/workflow/howto/local-development) or deploy it. Once the app is running, we can trigger the workflow using the following code:

```ts
import { Client } from "@upstash/workflow";

const client = new Client({ token: "<QSTASH_TOKEN>" });
const { workflowRunId } = await client.trigger({
  url: "https://<YOUR_WORKFLOW_ENDPOINT>/<YOUR-WORKFLOW-ROUTE>",
  body: { "prompt": "How is the weather in San Francisco around this time?" }
});
```

The workflow will execute, and we can view the logs in `the Workflow dashboard`

### Advanced Implementation with Tools

Tools allow the AI model to perform specific actions during text generation. You can learn more about tools in the [Vercel AI SDK documentation](https://sdk.vercel.ai/docs/ai-sdk-core/tools-and-tool-calling).

When using tools with Upstash Workflow, each tool execution must be wrapped in a workflow step.

<Info>
The `maxSteps` parameter must be greater than 1 when using tools to allow the model to process tool results and generate final responses. See the [tool steps documentation](https://sdk.vercel.ai/docs/ai-sdk-core/tools-and-tool-calling#tool-steps) for detailed explanation.
</Info>

```typescript {24-30, 33}
import { z } from 'zod';
import { serve } from "@upstash/workflow/nextjs";
import { WorkflowAbort } from '@upstash/workflow';
import { generateText, ToolExecutionError, tool } from 'ai';

import { createWorkflowOpenAI } from './model';

export const { POST } = serve<{ prompt: string }>(async (context) => {
  const openai = createWorkflowOpenAI(context);

const prompt = await context.run("get prompt", async () => {
    return context.requestPayload.prompt;
  });

try {
    const result = await generateText({
      model: openai('gpt-3.5-turbo'),
      tools: {
        weather: tool({
          description: 'Get the weather in a location',
          parameters: z.object({
            location: z.string().describe('The location to get the weather for'),
          }),
          execute: ({ location }) => context.run("weather tool", () => {
	        // Mock data, replace with actual weather API call
            return {
              location,
              temperature: 72 + Math.floor(Math.random() * 21) - 10,
            };
          })
        }),
      },
      maxSteps: 2,
      prompt,
    });

await context.run("text", () => {
      console.log(`TEXT: ${result.text}`);
      return result.text;
    });
  } catch (error) {
    if (error instanceof ToolExecutionError && error.cause instanceof WorkflowAbort) {
      throw error.cause;
    } else {
      throw error;
    }
  }
});
```

When called with the same prompt as above, we will see the following logs:

<img />

## Important Considerations

When using Upstash Workflow with the Vercel AI SDK, there are several critical requirements that must be followed:

### Step Execution Order

The most critical requirement is that `generateText` cannot be called before any workflow step. Always have a step before `generateText`. This could be a step which gets the prompt:

<CodeGroup>
```typescript ❌ Wrong {4}
export const { POST } = serve<{ prompt: string }>(async (context) => {
  const openai = createWorkflowOpenAI(context);

// Will throw "prompt is undefined"
  const result = await generateText({
    model: openai('gpt-3.5-turbo'),
    prompt: context.requestPayload.prompt
  });
});
```

```typescript ✅ Correct {3-7}
export const { POST } = serve<{ prompt: string }>(async (context) => {
  const openai = createWorkflowOpenAI(context);

// Get prompt in a step first
  const prompt = await context.run("get prompt", async () => {
    return context.requestPayload.prompt;
  });

const result = await generateText({
    model: openai('gpt-3.5-turbo'),
    prompt
  });
});
```
</CodeGroup>

### Error Handling Pattern

You must use the following error handling pattern exactly as shown. The conditions and their handling should not be modified:

```typescript {3-9}
try {
  // Your generation code
} catch (error) {
  if (error instanceof ToolExecutionError && error.cause instanceof WorkflowAbort) {
    throw error.cause;
  } else {
    throw error;
  }
}
```

### Tool Implementation

When implementing tools:
* Each tool's `execute` function must be wrapped in a `context.run()` call
* Tool steps should have descriptive names for tracking
* Tools must follow the same error handling pattern as above

Example:
```typescript
execute: ({ location }) => context.run("weather tool", () => {
  // Mock data, replace with actual weather API call
  return {
    location,
    temperature: 72 + Math.floor(Math.random() * 21) - 10,
  };
})
```

# Anthropic
Source: https://upstash.com/docs/workflow/integrations/anthropic

The standard way to call a third-party endpoint in your workflow is by using [`context.call`](/docs/workflow/basics/context#context-call).

However, if you need to call the Anthropic endpoint for text generation ([`/v1/messages`](https://docs.anthropic.com/en/api/messages)), you can leverage the type-safe method `context.api.anthropic.call` method:

<Note>
  `context.api.anthropic.call` is not yet available in
  [workflow-py](https://github.com/upstash/workflow-py). You can use `context.call` instead to work with Anthropic. See our
  [Roadmap](/docs/workflow/roadmap) for feature parity plans and
  [Changelog](/docs/workflow/changelog) for updates.
</Note>

```ts
const { status, body } = await context.api.anthropic.call(
  "Call Anthropic",
  {
    token: "<ANTHROPIC_API_KEY>",
    operation: "messages.create",
    body: {
      model: "claude-3-5-sonnet-20241022",
      max_tokens: 1024,
      messages: [
          {"role": "user", "content": "Hello, world"}
      ]
    },
  }
);

// get text:
console.log(body.content[0].text)
```

The SDK provides predefined types for the body field in both the request parameters and the response, simplifying common use cases. If you need to customize these types, you can override them as shown below:

```ts
type ResponseBodyType = { ... }; // Define your response body type
type RequestBodyType = { ... };  // Define your request body type

const { status, body } = await context.api.anthropic.call<
  ResponseBodyType,
  RequestBodyType
>(
  "Call Anthropic",
  {
    ...
  }
);
```

# Datadog - Upstash QStash Integration
Source: https://upstash.com/docs/workflow/integrations/datadog

This guide walks you through connecting your Datadog account with Upstash QStash for monitoring and analytics of your message delivery, retries, DLQ, and schedules.

<Check >
**Integration Scope**

Upstash Datadog Integration covers Prod Pack.

</Check>

## **Step 1: Log in to Your Datadog Account**

1. Go to [Datadog](https://www.datadoghq.com/) and sign in.

## **Step 2: Install Upstash Application**

1. In Datadog, open the Integrations page.
2. Search for "Upstash" and open the integration.

![integration-tab.png]()

Click "Install" to add Upstash to your Datadog account.

![installation.png]()

## **Step 3: Connect Accounts**

After installing Upstash, click "Connect Accounts". Datadog will redirect you to Upstash to complete account linking.

![connect-acc.png]()

## **Step 4: Select Account to Integrate**

1. On Upstash, select the Datadog account to integrate.
2. Personal and team accounts are supported.

**Caveats**

* The integration can be established once at a time. To change the account scope (e.g., add/remove teams), re-establish the integration from scratch.

![personal.png]()

![team.png]()

## **Step 5: Wait for Metrics Availability**

Once the integration is completed, metrics from QStash (publish counts, success/error rates, retries, DLQ, schedule executions) will start appearing in Datadog dashboards shortly.

![upstash-dashboard.png]()

## **Step 6: Datadog Integration Removal Process**

From Datadog → Integrations → Upstash, press "Remove" to break the connection.

### Confirm Removal

Upstash will stop publishing metrics after removal. Ensure any Datadog API keys/configurations for this integration are also removed on the Datadog side.

## **Conclusion**

You’ve connected Datadog with Upstash QStash. Explore Datadog dashboards to monitor message delivery performance and reliability.

If you need help, contact support.

# OpenAI
Source: https://upstash.com/docs/workflow/integrations/openai

### Calling OpenAI

The standard way to call a third-party endpoint in your workflow is by using [`context.call`](/docs/workflow/basics/context#context-call).

However, if you need to call the OpenAI endpoint for text generation ([`/v1/chat/completions`](https://platform.openai.com/docs/api-reference/chat)), you can leverage the type-safe method `context.api.openai.call` method:

<Note>
  `context.api.openai.call` is not yet available in
  [workflow-py](https://github.com/upstash/workflow-py). You can use `context.call` instead to work with OpenAI. See our
  [Roadmap](/docs/workflow/roadmap) for feature parity plans and
  [Changelog](/docs/workflow/changelog) for updates.
</Note>

```typescript OpenAI
const { status, body } = await context.api.openai.call(
  "Call OpenAI",
  {
    token: "<OPENAI_API_KEY>",
    operation: "chat.completions.create",
    body: {
      model: "gpt-4o",
      messages: [
        {
          role: "system",
          content: "Assistant says 'hello!'",
        },
        {
          role: "user",
          content: "User shouts back 'hi!'"
        }
      ],
    },
  }
);

// get text:
console.log(body.content[0].text)
```

```ts
type ResponseBodyType = { ... }; // Define your response body type
type RequestBodyType = { ... };  // Define your request body type

const { status, body } = await context.api.openai.call<
  ResponseBodyType,
  RequestBodyType
>(
  "Call OpenAI",
  {
    ...
  }
);
```

### OpenAI Compatible Provider

If you want to call an OpenAI compatible provider, you can do so using the `baseURL` parameter:

```ts
const { status, body } = await context.api.openai.call(
  "Call Deepseek",
  {
    baseURL: "https://api.deepseek.com",
    token: process.env.DEEPSEEK_API_KEY,
    operation: "chat.completions.create",
    body: {
      model: "deepseek-chat",
      messages: [
        {
          role: "system",
          content: "Assistant says 'hello!'",
        },
        {
          role: "user",
          content: "User shouts back 'hi!'"
        }
      ],
    },
  }
);
```

# Prometheus - Upstash QStash Integration
Source: https://upstash.com/docs/workflow/integrations/prometheus

To monitor your QStash metrics in Prometheus and visualize in Grafana, follow these steps:

<Check >
**Integration Scope**

Upstash Prometheus Integration covers Prod Pack.

</Check>

## **Step 1: Enable Prometheus in Upstash Console**

1. Open the Upstash Console and navigate to QStash.
2. Go to Settings → Monitoring.
3. Enable Prometheus to allow scraping QStash metrics.

![configuration.png]()

## **Step 2: Copy Monitoring Token**

1. After enabling, a monitoring token is generated and displayed.
2. Copy the token. It will be used to authenticate Prometheus requests.

<Check >
**Header Format**

Send the token as `Authorization: Bearer <MONITORING_TOKEN>`.

</Check>

![monitoring-token.png]()

## **Step 3: Configure Prometheus (via Grafana Data Source)**

1. In Grafana, add a Prometheus data source.
2. Set the address to `https://api.upstash.com/monitoring/prometheus`.
3. In HTTP headers, add the monitoring token.

![datasource.png]()

![headers.png]()

Click <b>Test and Save</b>.

![datasource-final.png]()

## **Step 4: Import Dashboard**

You can use the Upstash Grafana dashboard to visualize QStash metrics.

Open the import dialog and use: <a href="https://grafana.com/grafana/dashboards/24206-upstash-qstash-dashboard/">Upstash QStash Dashboard</a>

![grafana-dashboard.png]()

## **Conclusion**

You’ve integrated QStash with Prometheus. Use Grafana to explore message throughput, retries, DLQ, schedules, and Upstash Workflows.

If you encounter issues, contact support.

# Resend
Source: https://upstash.com/docs/workflow/integrations/resend

The standard way to call a third-party endpoint in your workflow is by using [`context.call`](/docs/workflow/basics/context#context-call).

However, if you need to call the Resend endpoint to send emails ([`/emails`](https://resend.com/docs/api-reference/emails/send-email) or [`/emails/batch`](https://resend.com/docs/api-reference/emails/send-batch-emails)), you can leverage the type-safe method `context.api.resend.call` method:

<Note>
  `context.api.resend.call` is not yet available in
  [workflow-py](https://github.com/upstash/workflow-py). You can use `context.call` instead to work with Resend. See our
  [Roadmap](/docs/workflow/roadmap) for feature parity plans and
  [Changelog](/docs/workflow/changelog) for updates.
</Note>

```typescript Single Email
const { status, body } = await context.api.resend.call(
  "Call Resend",
  {
    token: "<RESEND_API_KEY>",
    body: {
      from: "Acme <onboarding@resend.dev>",
      to: ["delivered@resend.dev"],
      subject: "Hello World",
      html: "<p>It works!</p>",
    },
    headers: {
      "content-type": "application/json",
    },
  }
);
```

```typescript Batch Email {4}
const { status, body } = await context.api.resend.call(
  "Call Resend",
  {
    batch: true,
    token: "<RESEND_API_KEY>",
    body: [
      {
        from: "Acme <onboarding@resend.dev>",
        to: ["delivered@resend.dev"],
        subject: "Hello World",
        html: "<p>It works!</p>",
      },
      {
        from: "Acme <onboarding@resend.dev>",
        to: ["delivered@resend.dev"],
        subject: "Hello World",
        html: "<p>It works!</p>",
      },
    ],
    headers: {
      "content-type": "application/json",
    },
  }
);
```

</CodeGroup>

```ts
type IsBatch = true; // Set to either true or false
type ResponseBodyType = { ... }; // Define your response body type
type RequestBodyType = { ... };  // Define your request body type

const { status, body } = await context.api.resend.call<
  IsBatch,
  ResponseBodyType,
  RequestBodyType
>(
  "Call Resend",
  {
    ...
  }
);
```

# llms.txt
Source: https://upstash.com/docs/workflow/llms-txt

# Pricing
Source: https://upstash.com/docs/workflow/pricing

Upstash Workflow is based on QStash and uses a "pay-as-you-go" pricing model. You only incur costs when your app receives traffic, meaning there's no charge when it's not in use. Click [here](https://upstash.com/pricing/workflow) to view the pricing.

A workflow run consists of several QStash messages, with the total cost determined by the number of messages used.

You can track your current message usage and associated costs in the [Overview tab of the console](https://console.upstash.com/qstash?tab=details).

<img />

For detailed pricing information based on different plans, visit our [Workflow pricing page](https://upstash.com/pricing/workflow).

### Message Usage per Workflow Run

* [context.run](/docs/workflow/basics/context#context-run), [context.sleep](/docs/workflow/basics/context#context-sleep), [context.sleepUntil](/docs/workflow/basics/context#context-sleepuntil), or [context.waitForEvent](/docs/workflow/basics/context#context-waitforevent) commands generate a single message.
* The [context.call](/docs/workflow/basics/context#context-call) command generates two messages.
* Each step in a [parallel run](/docs/workflow/howto/parallel-runs) costs 1 extra message.
* If the workflow endpoint or URL in [context.call](/docs/workflow/basics/context#context-call) returns an error or is unreachable, the workflow SDK will retry the call (up to 3 times by default). Each retry counts as a new message.

- [Astro](https://upstash.com/docs/workflow/quickstarts/astro.md)
- [Cloudflare Workers](https://upstash.com/docs/workflow/quickstarts/cloudflare-workers.md)
- [Express.js](https://upstash.com/docs/workflow/quickstarts/express.md)
- [FastAPI](https://upstash.com/docs/workflow/quickstarts/fastapi.md)
- [Flask](https://upstash.com/docs/workflow/quickstarts/flask.md)
- [Hono](https://upstash.com/docs/workflow/quickstarts/hono.md)
- [Next.js & FastAPI](https://upstash.com/docs/workflow/quickstarts/nextjs-fastapi.md)
- [Next.js & Flask](https://upstash.com/docs/workflow/quickstarts/nextjs-flask.md)
- [Nuxt](https://upstash.com/docs/workflow/quickstarts/nuxt.md)
- [Supported Platforms](https://upstash.com/docs/workflow/quickstarts/platforms.md)
- [SolidJS](https://upstash.com/docs/workflow/quickstarts/solidjs.md)
- [SvelteKit](https://upstash.com/docs/workflow/quickstarts/svelte.md)
- [TanStack Start](https://upstash.com/docs/workflow/quickstarts/tanstack-start.md)
- [Next.js](https://upstash.com/docs/workflow/quickstarts/vercel-nextjs.md)

# Roadmap
Source: https://upstash.com/docs/workflow/roadmap

# JavaScript SDK
Source: https://upstash.com/docs/workflow/sdk/workflow-js

# Python SDK
Source: https://upstash.com/docs/workflow/sdk/workflow-py

# General
Source: https://upstash.com/docs/workflow/troubleshooting/general

## Running Steps Inside try/catch Blocks

When running steps (run, sleep, call, or any other step) inside a try/catch block, you'll encounter the following error:

```
WorkflowAbort: This is an Upstash Workflow error thrown after
a step executes. It is expected to be raised. Make sure that
you await for each step. Also, if you are using try/catch
blocks, you should not wrap context.run/sleep/sleepUntil/call
methods with try/catch. Aborting workflow after executing
step 'some-step'.
```

The `WorkflowAbort` error is thrown by the Workflow SDK when a step executes successfully. When you run a step inside a try/catch block, you have two primary options:

1. **Re-throw WorkflowAbort**: If you need a try/catch block, re-throw the `WorkflowAbort` error:

2. **Avoid Running Steps in try/catch**: The simplest solution is to not wrap steps in try/catch blocks. If you have a `context.run` inside try/catch, you can try putting the try/catch inside the context.run.

```typescript TypeScript {1, 6-7}
import { WorkflowAbort } from '@upstash/workflow';

try {
  await context.run( ... );
} catch (error) {
  if (error instanceof WorkflowAbort) {
    throw error;
  } else {
    // handle other errors
  }
}
```

``` python Python {1, 6-7}
from upstash_workflow import WorkflowAbort

try:
    await context.run( ... )
except Exception as e:
    if isinstance(e, WorkflowAbort):
        raise e
    else:
        # handle other errors

```

</CodeGroup>

## `context.requestPayload` Becoming Undefined

### Headers Considerations

In some frameworks, you may need to pass specific headers for the workflow to access `requestPayload`:

* Try passing `Content-type: text/plain` or `Content-type: application/json` headers when starting the workflow.
* Note that `publishJSON` can only publish `Content-type: application/json`.

### `context.call` Execution

[During a workflow run, the endpoint will be called multiple times](/docs/workflow/basics/how). While executing `context.call`, the endpoint is called at least twice, with the SDK attempting to run the route function until the first step for custom authorization.

Accessing `context.requestPayload` before any step can result in it becoming undefined:

```typescript TypeScript {2-4, 8}
export const { POST } = serve(async (context) => {
  // Will print undefined while executing context.call
  const payload = context.requestPayload
  console.log(payload)

// ... steps or any other code

context.call( ... )
})
```

``` python Python {3-5, 9}
@serve.post("/api/example")
async def example(context: AsyncWorkflowContext[str]) -> None:
    # Will print None while executing context.call
    payload = context.request_payload
    print(payload)

# ... steps or any other code

context.call( ... )

```

</CodeGroup>

This behavior stems from the internal mechanics of `context.call`, and resolving this specific interaction is on our roadmap. Note that if you are passing `context.requestPayload` as a parameter to `context.call`, the payload remains intact. However, during the actual execution of `context.call`, the `context.requestPayload` becomes undefined due to the SDK's internal workflow processing steps.

To fix this issue, you can try adding a step which returns the payload:

```typescript TypeScript {2-4, 7}
export const { POST } = serve(async (context) => {
  // Payload will never be undefined
  const payload = await context.run("get payload", () => context.requestPayload)

// ... steps or any other code

context.call( ... )
})
```

``` python Python {4-8, 12}
@serve.post("/api/example")
async def example(context: AsyncWorkflowContext[str]) -> None:

async def _get_payload() -> str:
        return context.request_payload

# Payload will never be None
    payload = await context.run("get payload", _get_payload)

# ... steps or any other code

context.call( ... )

```

</CodeGroup>

You can find an example of this usage in [our documentation on usage with AI SDK](/docs/workflow/integrations/aisdk).

## Verification Failed Scenarios

When [QStash signature verification](/docs/workflow/howto/security#using-qstashs-built-in-request-verification-recommended) is enabled, you might encounter an error like:

```
Failed to verify that the Workflow request comes from QStash: some-error

If signature is missing, trigger the workflow endpoint by publishing your request to QStash instead of calling it directly.

If you want to disable QStash Verification, you should clear env variables QSTASH_CURRENT_SIGNING_KEY and QSTASH_NEXT_SIGNING_KEY
```

Troubleshooting verification errors:

* Ensure you [start the workflow using `client.trigger` or by publishing to QStash](/docs/workflow/howto/start).
* Verify that `QSTASH_CURRENT_SIGNING_KEY` and `QSTASH_NEXT_SIGNING_KEY` environment variables are correct.
* Pass [appropriate `Content-type` headers](/docs/workflow/troubleshooting/general#headers-considerations) when starting the workflow.

## Authorization Error Handling

Consider this workflow:

```typescript TypeScript {2-5}
export const { POST } = serve(async (context) => {

if (someCondition()) => {
    return;
  }

// rest of the workflow
})
```

``` python Python {3-4}
@serve.post("/api/example")
async def example(context: AsyncWorkflowContext[str]) -> None:
    if some_condition():
        return

# rest of the workflow

```

</CodeGroup>

Returning before running any steps will result in:
* HTTP status: 400
* Error message: `Failed to authenticate Workflow request.`

This behavior is a direct result of the [custom authorization mechanism](/docs/workflow/howto/security#custom-authorization-method). The Workflow SDK interprets an early function return without executing any steps as an authentication failure.

If the function `someCondition()` is non-deterministic, the recommended approach is to transform this condition into an explicit workflow step. Here's the recommended pattern for handling such non-deterministic conditions:

```typescript TypeScript {3-6}
export const { POST } = serve(async (context) => {

const shouldReturn = await context.run("check condition", () => someCondition())
  if (shouldReturn) => {
    return;
  }

// rest of the workflow
})
```

``` python Python {4-9}
@serve.post("/api/example")
async def example(context: AsyncWorkflowContext[str]) -> None:

async def _check_condition() -> bool:
        return some_condition()

should_return = await context.run("check condition", _check_condition)
    if should_return:
        return

# rest of the workflow

```

</CodeGroup>

## Retry Configuration

Retry settings can be configured in two locations:

1. [**Workflow Start** (client.trigger)](/docs/workflow/howto/start): For the triggered workflow run
   * Default retries: 3

2. [**Context Call**](/docs/workflow/basics/context#context-call): For third party requests
   * Default retries: 0

## Verbose Mode Diagnostics

Use [verbose mode](/docs/workflow/basics/serve#verbose) to diagnose workflow issues.

The logs in this section should be seen very rarely. If you observe these logs consistently, you can reach out to our support.

### Localhost in URL Warning

```
Workflow URL contains localhost. This can happen in local development,
but shouldn't happen in production unless you have a route which contains
localhost. Received: ...
```

This error indicates that the workflow URL has localhost. Publish requests will fail and workflow won't be able to run.

**Potential Solutions:**
* Verify [baseUrl](/docs/workflow/basics/serve#baseurl)
* Check UPSTASH_WORKFLOW_URL
* Explicitly pass the full [url](/docs/workflow/basics/serve#url)

### Deduplication Log
Since QStash has at least once delivery guarantee, there is a very small chance that a step will run twice. This is why we suggest [idempotancy](/docs/workflow/basics/caveats#ensure-idempotency-in-context-run). When this happens, the duplicate step should print the following log and terminate:

```
Upstash Workflow: The step 'some-step' with id 'step-index' has run twice during workflow execution. Rest of the workflow will continue running as usual.
```

### Network Issue Warnings

In rare instances, the workflow endpoint may complete its task successfully but fail to send a proper response. The SDK is designed to detect such occurrences. When this happens, the workflow endpoint will return a `200` status code and log one of the following three warnings:

```
Workflow run wfr-*** already exists. A new one isn't created.
tried to append to a cancelled workflow. exiting without publishing.
Failed to remove workflow run wfr-*** as it doesn't exist.
```

A similar issue can occur if you have two parallel context.call steps at the end of your workflow. While the workflow will execute successfully, you may see this warnings:

```
Couldn't fetch workflow run steps. This can happen if the workflow run successfully ends before some callback is executed.
```

## HTTPS Protocol Issue

The Workflow SDK automatically infers the protocol (HTTP or HTTPS) based on the incoming request object in your application.

However, if your app is deployed behind a proxy (e.g., Railway or similar platforms), the proxy may terminate SSL and forward the request to your app using plain HTTP.
This can cause the SDK to mistakenly infer that the request is using HTTP instead of HTTPS.

To fix this, explicitly set the `UPSTASH_WORKFLOW_URL` environment variable to the base URL of your application.
This disables automatic protocol inference and uses the provided static URL instead.

If you’re using Express.js behind a front-facing proxy, an alternative solution is to enable [proxy trust](https://expressjs.com/en/api.html#app.set) so Express correctly identifies the original protocol from the X-Forwarded-Proto header:

```javascript
app.set("trust proxy", true)
```

## Workflow Stuck in First Step

Imagine that you trigger your workflow with [client.trigger](/docs/workflow/basics/client/trigger) and the workflow starts (you see the run in the dashboard), but it doesn't proceed beyond the first step.

If it appears like the initial step has failed:
* Expand the step in the dashboard to see detailed logs to check for any error messages or stack traces that can provide insights into what went wrong.
* Ensure that the workflow endpoint is accessible. You can test by sending a `curl` request to see if the request lands on the endpoint.
* Ensure that the URL you passed to the `client.trigger` method matches the workflow endpoint URL.
* Verify that you're using the latest SDK version both in the workflow endpoint definition and in the code that calls `client.trigger`.

If it appears like the initial step has completed but the workflow is still stuck:
* Workflow SDK could be unable to correctly infer the workflow URL due to a proxy or an issue in the request object. To check if this is the issue, try passing the [`baseUrl` parameter to the `serve` method](/docs/workflow/basics/serve/advanced#param-base-url). This will override the automatic URL inference and use the provided base URL instead.

## Non-workflow Destination Error

Full error:

```
detected a non-workflow destination for trigger/invoke.
make sure you are sending the request to the correct endpoint
```

This error occurs when you call a non-workflow endpoint with `client.trigger` or via Request Builder on Upstash Console. If you check Upstash Console, you will see that the workflow run has started but failed before running any steps:

<img />

Another way you can encounter this error is if you are calling a workflow endpoint on an older SDK version (before 0.2.17 in TypeScript and 0.1.4 in Python) from a newer SDK version. If this happens, in the logs, you will see that the first step of the workflow run has completed successfully, but the workflow fails immediately after that with the same error.

To fix this error, ensure that:
* You are calling a valid workflow endpoint.
* Both the caller and the workflow endpoint are using the latest SDK versions.

# Vercel
Source: https://upstash.com/docs/workflow/troubleshooting/vercel

# Common Issues and Solutions

### Preview Deployment Protection

**Problem:**
When Deployment Protection setting is enabled on Vercel, it's not possible to trigger and complete a workflow run on a preview deployment.

**Solution:**
Vercel provides a way to bypass this protection by using a bypass secret. To create one, follow these steps:

<Steps>
	<Step title="Settings">Go to **Deployment Protection** section under your Vercel project settings.</Step>

<Step title="Find related section">
		Click on **Add Secret** under **Protection Bypass for Automation** section.
  			<img />
	</Step>

<Step title="Generate a bypass token">Don't forget to save it and store it as an environment variable (e.g., `VERCEL_AUTOMATION_BYPASS_SECRET`).</Step>
</Steps>

Now that you have a bypass token, you need to pass it as a header in two places to bypass deployment protection.

## Using the Bypass Secret

### Step 1: Configure QStash Client with Headers

[Configure the QStash client](/docs/workflow/basics/serve/advanced#param-qstash-client) with the bypass header in your workflow serve options. This ensures that all workflow steps, including `context.invoke` calls, will include the bypass header automatically:

```ts
import { Client } from '@upstash/qstash'
import { serve } from '@upstash/workflow/nextjs'

export const { POST } = serve<string>(async (context) => {
  // your workflow logic
}, {
  qstashClient: new Client({
    token: process.env.QSTASH_TOKEN!,
    headers: {
      "x-vercel-protection-bypass": process.env.VERCEL_AUTOMATION_BYPASS_SECRET!
    }
  })
})
```

### Step 2: Pass Header When Triggering

When [triggering the workflow](/docs/workflow/howto/start) using `curl` or `client.trigger`, you must also pass the bypass secret as a header:

<CodeGroup>
```ts client.trigger
import { Client } from "@upstash/workflow";

const client = new Client({ token: "<QSTASH_TOKEN>" })

await client.trigger({
  url: "https://vercel-preview.com/workflow",
  headers: {
    "x-vercel-protection-bypass": process.env.VERCEL_AUTOMATION_BYPASS_SECRET!
  },
  body: "Hello world!"
})
```

```bash cURL
curl -X POST \
  'https://vercel-preview.com/workflow' \
  -H 'x-vercel-protection-bypass: <PROTECTION_BYPASS_SECRET>' \
  -d 'Hello world!'
```
</CodeGroup>

<Warning>
	Note that you should apply both of the steps above. The header must be passed when triggering the workflow AND configured in the QStash client for subsequent workflow steps to work properly.
</Warning>