Overview

Secondary indexing and querying for Upstash Redis

@upstash/query offers secondary indexing and search capabilities for Upstash Redis. It is fully managed by Upstash and scales automatically.

github.com/upstash/query

Features

• E2E Typesafe: Fully typed API with TypeScript generics to offer the best developer experience.
• Secondary Indexing: Create indexes on your data and query them with a simple API.
• Range Queries: Query your data with range queries. Either numeric or lexicographic.

Quickstart

1. Install dependencies

   pnpm

   pnpm add @upstash/query @upstash/redis
   

   npm

   npm install @upstash/query @upstash/redis
   

   bun

   bun install @upstash/query @upstash/redis
   

   yarn

   yarn add @upstash/query @upstash/redis
   
2. Set environment variables

   .env

   UPSTASH_REDIS_REST_URL="..."
   UPSTASH_REDIS_REST_TOKEN="..."
   
3. Import the packages and create a client

   import { Redis } from "@upstash/redis";
   // import { Redis } from "@upstash/redis/cloudflare"; // for Cloudflare Workers
   // import { Redis } from "@upstash/redis/fastly"; // for Fastly Compute@Edge
   import { Query } from "@upstash/query";
   
   
   const q = new Query({
       // it's important to turn off deserialization 
       // because @upstash/query handles deserialization itself
       redis: Redis.fromEnv({ automaticDeserialization: false }),
     });
   
   
4. Define a type for your data

   type User = {
       id: string;
       name: string;
       organization: string;
       email: string;
     };
   
5. Create a collection of the same type and an index on the collection

   
     /**
      * Create your first collection.
      *
      * Please make sure you're passing in a type to take full advantage of @upstash/query
      */
     const users = q.createCollection<User>("users");
   
     /**
      * Create a searchable index on the collection and specify which terms we are filtering by
      * terms are fully typed as long as you have defined a custom type when creating the collection
      */
     const usersByOrganization = users.createIndex({
       name: "users_by_organization",
       terms: ["organization"],
     });
   
   

   It’s important to declare indices before you start adding data to your collection. Otherwise, they will not be indexed. In cases where you want to add an index to an existing collection, you can use the .reIndex() method.

6. Time to add some data

   
   const user: User = {
     id: "chronark",
     name: "Andreas Thomas",
     organization: "Upstash",
     email: "[e-mail]",
   };
   // Create and store your first user
   await users.set("documentId", user);
   
   
7. Run your first query against the index

   
   /**
    * Now we can use the previously created index to query by organization
    */
   const upstashEmployees = await usersByOrganization.match({
         organization: "Upstash" 
      });
   /**
    * [
    *     {
    *         id: "documentId",
    *         ts: 000, // the timestamp when created or last updated
    *         data: {
    *             id: "chronark",
    *             name: "Andreas Thomas",
    *             organization: "Upstash",
    *             email: "[e-mail]"
    *         }
    *     }
    * ]
    */