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 v3.0.0 onwards, Predis uses query dialect 2 by default. Redis Search methods such as ftSearch() 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 Predis client library if you haven't already done so.

Add the following dependencies:

Language:

Foundational: Import required dependencies for Redis Search and JSON operations

<?php

require 'vendor/autoload.php';

use Predis\Client as PredisClient;

use Predis\Command\Argument\Search\AggregateArguments;
use Predis\Command\Argument\Search\CreateArguments;
use Predis\Command\Argument\Search\SearchArguments;
use Predis\Command\Argument\Search\SchemaFields\NumericField;
use Predis\Command\Argument\Search\SchemaFields\TextField;
use Predis\Command\Argument\Search\SchemaFields\TagField;

Create data

Create some test data to add to your database:

Language:

Foundational: Create sample JSON data structures for indexing and querying

        $user1 = json_encode([
            'name' => 'Paul John',
            'email' => '[email protected]',
            'age' => 42,
            'city' => 'London',
        ], JSON_THROW_ON_ERROR);
        
        $user2 = json_encode([
            'name' => 'Eden Zamir',
            'email' => '[email protected]',
            'age' => 29,
            'city' => 'Tel Aviv',
        ], JSON_THROW_ON_ERROR);
        
        $user3 = json_encode([
            'name' => 'Paul Zamir',
            'email' => '[email protected]',
            'age' => 35,
            'city' => 'Tel Aviv',
        ], JSON_THROW_ON_ERROR);

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: Connect to a Redis server and establish a client connection

        $r = new PredisClient([
            'scheme'   => 'tcp',
            'host'     => '127.0.0.1',
            'port'     => 6379,
            'password' => '',
            'database' => 0,
        ]);

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

Language:

Foundational: Create a search index for JSON documents with field schema and prefix filtering

        $schema = [
            new TextField('$.name', 'name'),
            new TagField('$.city', 'city'),
            new NumericField('$.age', "age"),
        ];
        
        try {
        $r->ftCreate("idx:users", $schema,
            (new CreateArguments())
                ->on('JSON')
                ->prefix(["user:"]));
        }
        catch (Exception $e) {
            echo $e->getMessage(), PHP_EOL;
        }

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:

Language:

Foundational: Store JSON documents with indexed key prefixes for automatic indexing

        $r->jsonset('user:1', '$', $user1);
        $r->jsonset('user:2', '$', $user2);
        $r->jsonset('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 full-text and range queries on indexed JSON documents using FT.SEARCH

        $res = $r->ftSearch("idx:users", "Paul @age:[30 40]");
        echo json_encode($res), PHP_EOL;
        // >>> [1,"user:3",["$","{\"name\":\"Paul Zamir\",\"email\":\"[email protected]\",\"age\":35,\"city\":\"Tel Aviv\"}"]]

Specify query options to return only the city field:

Language:

Restrict query results: Use query options to return specific fields from search results

        $arguments = new SearchArguments();
        $arguments->addReturn(3, '$.city', true, 'thecity');
        $arguments->dialect(2);
        $arguments->limit(0, 5);

        $res = $r->ftSearch("idx:users", "Paul", $arguments);

        echo json_encode($res), PHP_EOL;
        // >>> [2,"user:1",["thecity","London"],"user:3",["thecity","Tel Aviv"]]

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

Language:

Aggregation: Use aggregation queries to group and count results from indexed documents

        $ftAggregateArguments = (new AggregateArguments())
            ->groupBy('@city')
            ->reduce('COUNT', true, 'count');

        $res = $r->ftAggregate('idx:users', '*', $ftAggregateArguments);
        echo json_encode($res), PHP_EOL;
        // >>> [2,["city","London","count","1"],["city","Tel Aviv","count","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.

Language:

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

        $hashSchema = [
            new TextField('name'),
            new TagField('city'),
            new NumericField('age'),
        ];
        
        try {
        $r->ftCreate("hash-idx:users", $hashSchema,
            (new CreateArguments())
                ->on('HASH')
                ->prefix(["huser:"]));
        }
        catch (Exception $e) {
            echo $e->getMessage(), PHP_EOL;
        }

You use hmset() to add the hash documents instead of jsonset(). Supply the fields as an array directly, without using json_encode().

Language:

Foundational: Store hash documents using HSET for indexed retrieval

        $r->hmset('huser:1', [
            'name' => 'Paul John',
            'email' => '[email protected]',
            'age' => 42,
            'city' => 'London',
        ]);
        
        $r->hmset('huser:2', [
            'name' => 'Eden Zamir',
            'email' => '[email protected]',
            'age' => 29,
            'city' => 'Tel Aviv',
        ]);
        
        $r->hmset('huser:3', [
            'name' => 'Paul Zamir',
            'email' => '[email protected]',
            'age' => 35,
            'city' => 'Tel Aviv',
        ]);

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 almost the same except that the fields are returned directly in the result array rather than in a JSON string with $ as its key:

Language:

Query data: Query hash documents using the same search syntax as JSON with different result formatting

        $res = $r->ftSearch("hash-idx:users", "Paul @age:[30 40]");
        echo json_encode($res), PHP_EOL;
        // >>> [1,"huser:3",["name","Paul Zamir","email","[email protected]","age","35","city","Tel Aviv"]]

Bulk import with HIMPORT

From Redis Open Source 8.10, you can also add the hash documents with the HIMPORT command family. This creates the same hashes as hmset(), but lets Redis store them as compact hashes, which use less memory when many keys share the same field names. Redis Search indexes these hashes in the same way.

Declare the field names once by calling himport() with PREPARE, then create each document by calling it with SET, passing only its values, in the same order as the field names. Use a pipeline to send all the imports in one round trip:

Language:

Bulk ingestion: Import hash documents as compact hashes using HIMPORT PREPARE and a pipeline of HIMPORT SET calls

        $himportRes = $r->pipeline(function ($pipe) {
            $pipe->himport('PREPARE', 'huser', ['name', 'email', 'age', 'city']);

            $pipe->himport('SET', 'huser:1', 'huser', ['Paul John', '[email protected]', 42, 'London']);
            $pipe->himport('SET', 'huser:2', 'huser', ['Eden Zamir', '[email protected]', 29, 'Tel Aviv']);
            $pipe->himport('SET', 'huser:3', 'huser', ['Paul Zamir', '[email protected]', 35, 'Tel Aviv']);
        });

HIMPORT SET replaces any existing key, so running this code after the hmset() calls leaves you with the same three documents. The query returns the same result, although the fields can appear in a different order.

Note:

HIMPORT requires Predis v3.6.0 or later, and Predis marks its support as experimental, so the API might change. Redis Cloud and Redis Software don't support HIMPORT.

More information

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

	Products	Version
	Develop with Redis Clients, data types, programmability, and Redis for AI. RedisVL is listed separately.
	Libraries and tools Client libraries, observability, and cloud integrations. Redis Data Integration is listed separately.
	RedisVL
	Redis Software
	Redis Cloud
	Redis for Kubernetes
	Redis Open Source
	Redis Iris context engine
	Redis Feature Form
	Redis Insight
	Redis Data Integration
	Glossary
	Command reference

Index and query documents

Initialize

Create data

Add the index

Add the data

Query the data

Differences with hash documents

Bulk import with HIMPORT

More information

On this page