Index and query documents

Learn how to use Redis Search with JSON and hash documents.

This example shows how to create a search index for JSON documents and run queries against the index. It then goes on to show the slight differences in the equivalent code for hash documents.

Note:

From v5.0.0 onwards, node-redis uses query dialect 2 by default. Redis Search methods such as ft.search() will explicitly request this dialect, overriding the default set for the server. See Query dialects for more information.

Initialize

Make sure that you have Redis Open Source or another Redis server available. Also install the node-redis client library if you haven't already done so.

Add the following dependencies:

Language:

Foundational: Import required modules for Redis client and query operations

import {
    createClient,
    SCHEMA_FIELD_TYPE,
    FT_AGGREGATE_GROUP_BY_REDUCERS,
    FT_AGGREGATE_STEPS,
} from 'redis';

Create data

Create some test data to add to your database. The example data shown below is compatible with both JSON and hash objects.

Language:

Foundational: Define sample data structures for indexing and querying examples

const user1 = {
    name: 'Paul John',
    email: '[email protected]',
    age: 42,
    city: 'London'
};

const user2 = {
    name: 'Eden Zamir',
    email: '[email protected]',
    age: 29,
    city: 'Tel Aviv'
};

const user3 = {
    name: 'Paul Zamir',
    email: '[email protected]',
    age: 35,
    city: 'Tel Aviv'
};

Add the index

Connect to your Redis database. The code below shows the most basic connection but see Connect to the server to learn more about the available connection options.

Language:

Foundational: Establish a connection to Redis for query operations

const client = await createClient();
await client.connect();

Create an index. In this example, only JSON documents with the key prefix user: are indexed. For more information, see Query syntax.

First, drop any existing index to avoid a collision. (The callback is required to avoid an error if the index doesn't already exist.)

Language:

Foundational: Drop an existing search index safely using error handling to avoid collisions

await client.ft.dropIndex('idx:users', { DD: true }).then(() => {}, () => {});

Then create the index:

Language:

Foundational: Create a search index for JSON documents with field definitions and aliases

await client.ft.create('idx:users', {
    '$.name': {
        type: SCHEMA_FIELD_TYPE.TEXT,
        AS: 'name'
    },
    '$.city': {
        type: SCHEMA_FIELD_TYPE.TEXT,
        AS: 'city'
    },
    '$.age': {
        type: SCHEMA_FIELD_TYPE.NUMERIC,
        AS: 'age'
    }
}, {
    ON: 'JSON',
    PREFIX: 'user:'
});

Add the data

Add the three sets of user data to the database as JSON objects. If you use keys with the user: prefix then Redis will index the objects automatically as you add them. Note that placing the commands in a Promise.all() call is an easy way to create a pipeline, which is more efficient than sending the commands individually.

Language:

Foundational: Add JSON documents with indexed key prefixes using Promise.all() for efficient pipelining

const [user1Reply, user2Reply, user3Reply] = await Promise.all([
    client.json.set('user:1', '$', user1),
    client.json.set('user:2', '$', user2),
    client.json.set('user:3', '$', user3)
]);

Query the data

You can now use the index to search the JSON objects. The query below searches for objects that have the text "Paul" in any field and have an age value in the range 30 to 40:

Language:

Query data: Execute a full-text search combined with numeric range filtering on indexed JSON documents

let findPaulResult = await client.ft.search('idx:users', 'Paul @age:[30 40]');

console.log(findPaulResult.total); // >>> 1

findPaulResult.documents.forEach(doc => {
    console.log(`ID: ${doc.id}, name: ${doc.value.name}, age: ${doc.value.age}`);
});
// >>> ID: user:3, name: Paul Zamir, age: 35

Specify query options to return only the city field:

Language:

Restrict query results: Project specific fields in query results to reduce data transfer and improve performance

let citiesResult = await client.ft.search('idx:users', '*',{
    RETURN: 'city'
});

console.log(citiesResult.total); // >>> 3

citiesResult.documents.forEach(cityDoc => {
    console.log(cityDoc.value);
});
// >>> { city: 'London' }
// >>> { city: 'Tel Aviv' }
// >>> { city: 'Tel Aviv' }

Use an aggregation query to count all users in each city.

Language:

Aggregate query results: Use aggregation queries to group and count results by field values for analytics

let aggResult = await client.ft.aggregate('idx:users', '*', {
    STEPS: [{
        type: FT_AGGREGATE_STEPS.GROUPBY,
        properties: '@city',
        REDUCE: [{
            type: FT_AGGREGATE_GROUP_BY_REDUCERS.COUNT,
            AS: 'count'
        }]
    }]
});

console.log(aggResult.total); // >>> 2

aggResult.results.forEach(result => {
    console.log(`${result.city} - ${result.count}`);
});
// >>> London - 1
// >>> Tel Aviv - 2

Differences with hash documents

Indexing for hash documents is very similar to JSON indexing but you need to specify some slightly different options.

When you create the schema for a hash index, you don't need to add aliases for the fields, since you use the basic names to access the fields anyway. Also, you must use HASH for the ON option when you create the index. The code below shows these changes with a new index called hash-idx:users, which is otherwise the same as the idx:users index used for JSON documents in the previous examples.

First, drop any existing index to avoid a collision.

Language:

Foundational: Drop an existing search index safely using error handling to avoid collisions

await client.ft.dropIndex('hash-idx:users', { DD: true }).then(() => {}, () => {});

Then create the new index:

Language:

Foundational: Create a search index for hash documents with HASH type specification

await client.ft.create('hash-idx:users', {
    'name': {
        type: SCHEMA_FIELD_TYPE.TEXT
    },
    'city': {
        type: SCHEMA_FIELD_TYPE.TEXT
    },
    'age': {
        type: SCHEMA_FIELD_TYPE.NUMERIC
    }
}, {
    ON: 'HASH',
    PREFIX: 'huser:'
});

You use hSet() to add the hash documents instead of json.set(), but the same flat userX objects work equally well with either hash or JSON:

Language:

Foundational: Add hash documents with indexed key prefixes using hSet() for automatic indexing

const [huser1Reply, huser2Reply, huser3Reply] = await Promise.all([
    client.hSet('huser:1', user1),
    client.hSet('huser:2', user2),
    client.hSet('huser:3', user3)
]);

The query commands work the same here for hash as they do for JSON (but the name of the hash index is different). The format of the result is also the same:

Language:

Query data: Execute the same full-text query pattern on hash documents as on JSON documents

let findPaulHashResult = await client.ft.search(
    'hash-idx:users', 'Paul @age:[30 40]'
);

console.log(findPaulHashResult.total); // >>> 1

findPaulHashResult.documents.forEach(doc => {
    console.log(`ID: ${doc.id}, name: ${doc.value.name}, age: ${doc.value.age}`);
});
// >>> ID: huser:3, name: Paul Zamir, age: 35

More information

See the Redis Search docs for a full description of all query features with examples.

Index and query documents

Initialize

Create data

Add the index

Add the data

Query the data

Differences with hash documents

More information

On this page