> ## Documentation Index
> Fetch the complete documentation index at: https://upstash-vector.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

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

<Card title="github.com/upstash/query" icon="github" href="https://github.com/upstash/query" />

## Features

* [x] **E2E Typesafe**: Fully typed API with TypeScript generics to offer the best developer experience.
* [x] **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

<Steps>
  <Step title="Install dependencies">
    <Tabs>
      <Tab title="pnpm">
        ```bash
        pnpm add @upstash/query @upstash/redis
        ```
      </Tab>

      <Tab title="npm">
        ```bash
        npm install @upstash/query @upstash/redis
        ```
      </Tab>

      <Tab title="bun">
        ```bash
        bun install @upstash/query @upstash/redis
        ```
      </Tab>

      <Tab title="yarn">
        ```bash
        yarn add @upstash/query @upstash/redis
        ```
      </Tab>
    </Tabs>
  </Step>

  <Step title="Set environment variables">
    ```env: .env
    UPSTASH_REDIS_REST_URL="..."
    UPSTASH_REDIS_REST_TOKEN="..."
    ```
  </Step>

  <Step title="Import the packages and create a client">
    ```ts
    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 }),
      });

    ```
  </Step>

  <Step title="Define a type for your data">
    ```ts
    type User = {
        id: string;
        name: string;
        organization: string;
        email: string;
      };
    ```
  </Step>

  <Step title="Create a collection of the same type and an index on the collection">
    ```ts

      /**
       * 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.
  </Step>

  <Step title="Time to add some data">
    ```ts

    const user: User = {
      id: "chronark",
      name: "Andreas Thomas",
      organization: "Upstash",
      email: "andreas@upstash.com",
    };
    // Create and store your first user
    await users.set("documentId", user);

    ```
  </Step>

  <Step title="Run your first query against the index">
    ```ts

    /**
     * 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: "andreas@upstash.com"
     *         }
     *     }
     * ]
     */
    ```
  </Step>
</Steps>