# Jedis — Redis Search quick reference

This reference covers the `FT.*` (Redis Search) surface of the Jedis client. It shows how Jedis *expresses* the canonical CLI form — it does not re-explain the query DSL. Read it after a reference that already states *what* to do.

- **Query DSL vocabulary** (delimiters, operators, escaping): [`../search-syntax-primitives.md`](../search-syntax-primitives.md). Do not duplicate that grammar here.
- **redis-py (Python) equivalents** for the same operations: [`python-redis-py.md`](./python-redis-py.md).
- **RedisVL** is a Python SDK only; there is no Java equivalent. For Java targets, this is the reference.

Examples below trace to specific files in `redis/jedis/src/test/java/io/redis/examples/` and the broader Jedis test suite, preserving the upstream `STEP_START`/`STEP_END` labels so you can pair-verify against the runnable Java source — and against the matching Python steps in [`python-redis-py.md`](./python-redis-py.md). The shared **Bicycle dataset** (`bicycle:<n>` JSON docs with `brand`, `model`, `description`, `price`, `condition`, `type`, `pickup_zone`, `store_location`, `description_embeddings`) is used throughout.

**Async / reactive:** Jedis is sync-only by design. For non-blocking I/O on Redis Search, use Lettuce — out of scope for v1 of this reference.

## Table of contents

1. [Minimum supported versions](#1-minimum-supported-versions)
2. [Client class choice](#2-client-class-choice)
3. [Connection setup](#3-connection-setup)
4. [Schema imports](#4-schema-imports)
5. [Create index — HASH](#5-create-index--hash)
6. [Create index — JSON](#6-create-index--json)
7. [FT.SEARCH idioms](#7-ftsearch-idioms)
8. [FT.AGGREGATE idioms](#8-ftaggregate-idioms)
9. [Cursors](#9-cursors)
10. [Vector queries](#10-vector-queries)
11. [FT.HYBRID](#11-fthybrid)
12. [Debugging](#12-debugging)
13. [Index management](#13-index-management)
14. [Common errors & version gotchas](#14-common-errors--version-gotchas)
15. [Upstream examples index](#15-upstream-examples-index)


## 1. Minimum supported versions

redis-py equivalent: see [`python-redis-py.md#1-minimum-supported-versions`](./python-redis-py.md#1-minimum-supported-versions).

| Component | Minimum | Notes |
|-----------|---------|-------|
| Jedis | **5.0** | 4.x predates the `redis.clients.jedis.search.schemafields.*` package and the fluent `SchemaField[]` API. Examples in this reference will not compile against 4.x. |
| Jedis (FT.HYBRID high-level API) | **6.0** | `ftHybrid` / `FTHybridParams` are not in Jedis 5.x — fall back to `sendCommand(SearchCommand.HYBRID, ...)` (see §11). |
| Redis server (FT.SEARCH / FT.AGGREGATE) | **7.4** | Redis Search ships built-in from Redis 8.0; on 7.4 the RediSearch module must be loaded. |
| Redis server (`FT.HYBRID`) | **8.4.0** | Hard floor. `ftHybrid` returns `JedisDataException: unknown command 'FT.HYBRID'` on older Redis. Fall back to pre-filter + `=>[KNN ...]` via FT.SEARCH. |
| Java | 8+ | Jedis 5.x targets Java 8 baseline; 6.x targets Java 11+. |

**DIALECT default:** Jedis does **not** set DIALECT on your behalf. Every query in this reference passes DIALECT 2 explicitly via `FTSearchParams.searchParams().dialect(2)` or `AggregationBuilder.dialect(2)`. GEOSHAPE `WITHIN`/`CONTAINS` predicates require DIALECT 3.


## 2. Client class choice

redis-py has a single client class (`redis.Redis`); no equivalent client-choice section — see [`python-redis-py.md#2-connection-setup`](./python-redis-py.md#2-connection-setup) for how the single class is constructed.

Jedis has accumulated several entry points. Pick **one** per project and stay consistent — mixing them in the same codebase forces conversions and confuses readers.

| Class | Use when… | Threading | Notes |
|-------|-----------|-----------|-------|
| `RedisClient` | **Current upstream default.** All examples under `redis/jedis/src/test/java/io/redis/examples` use this. Constructed via `RedisClient.create("redis://localhost:6379")`. | Internal pool; safe to share across threads. | Use this for new code. |
| `UnifiedJedis` | Single sync client without a pool wrapper — useful for tests, scripts, or single-threaded callers. | Single connection; **not** thread-safe. | Parent class of `RedisClient` and `JedisPooled`; appears in internal test base classes. |
| `JedisPooled` | Pre-`RedisClient` recommended pooled client. Still widely used in existing apps. | Internal `JedisPool`; thread-safe. | Functionally equivalent to `RedisClient` for FT.* calls. Don't rewrite working `JedisPooled` code just to swap names. |
| `Jedis` (legacy) | A single raw connection, the original 4.x-era API. | One connection; **not** thread-safe. Must be returned to a pool or `close()`'d per use. | Avoid in new code. Many community blog posts still show this pattern. |
| `JedisCluster` | Redis Cluster. | Cluster-aware pool. | FT.* indexes are not sharded across cluster slots — see Redis Search cluster docs before using. |

**Migration path:** `Jedis` → `JedisPooled` (same API + connection management) → `RedisClient` (same API, current upstream name). All three accept the same `ftSearch`, `ftCreate`, `ftAggregate` etc. methods, so migration is mostly a constructor swap.

**Divergence to flag:** upstream Jedis examples (`SearchQuickstartExample.java`) use `RedisClient.create("localhost", 6379)` while most public-internet blog posts and older Redis docs still show `UnifiedJedis` or `JedisPooled`. If you're porting code from those sources, the FT.* method names are identical — only the construction line differs.


## 3. Connection setup

redis-py equivalent: see [`python-redis-py.md#2-connection-setup`](./python-redis-py.md#2-connection-setup).

The canonical connect, from `SearchQuickstartExample.java` — STEP_START `connect`:

```java
import redis.clients.jedis.RedisClient;

RedisClient jedis = RedisClient.create("localhost", 6379);
// or, URI form (used in QueryFtExample.java, QueryEmExample.java, etc.):
RedisClient jedis2 = RedisClient.create("redis://localhost:6379");
```

`RedisClient` carries an internal pool and is safe to share across threads. Use it as a long-lived field; do not create one per request. Always `close()` it at application shutdown (or use try-with-resources for short-lived scripts):

```java
try (RedisClient jedis = RedisClient.create("redis://localhost:6379")) {
    // FT.* calls here
}
```

For TLS / auth, prefer the URI form: `redis://user:password@host:6379` or `rediss://...` for TLS. Configuration of pool size, timeouts, and SSL contexts goes through `DefaultJedisClientConfig.builder()` — out of scope here, see Jedis docs.


## 4. Schema imports

redis-py equivalent: see [`python-redis-py.md#3-schema-imports`](./python-redis-py.md#3-schema-imports).

The canonical Jedis import block for FT.* code, mirroring `SearchQuickstartExample.java` and `HomeJsonExample.java` STEP_START `import`:

```java
import redis.clients.jedis.RedisClient;
import redis.clients.jedis.exceptions.JedisDataException;
import redis.clients.jedis.json.Path2;
import redis.clients.jedis.search.*;                 // Query, SearchResult, Document,
                                                     // FTCreateParams, FTSearchParams,
                                                     // IndexDataType, RediSearchUtil
import redis.clients.jedis.search.schemafields.*;    // TextField, TagField, NumericField,
                                                     // GeoField, GeoShapeField, VectorField
import redis.clients.jedis.search.aggr.*;            // AggregationBuilder, AggregationResult,
                                                     // Reducers, SortedField, Row, Group
import redis.clients.jedis.args.SortingOrder;        // ASC / DESC
```

For FT.HYBRID (Redis ≥ 8.4.0, Jedis ≥ 6.0):

```java
import redis.clients.jedis.search.Combiners;
import redis.clients.jedis.search.Scorers;
import redis.clients.jedis.search.hybrid.FTHybridParams;
import redis.clients.jedis.search.hybrid.FTHybridSearchParams;
import redis.clients.jedis.search.hybrid.FTHybridVectorParams;
import redis.clients.jedis.search.hybrid.FTHybridPostProcessingParams;
import redis.clients.jedis.search.hybrid.HybridResult;
```

Notes:

- The schema field classes live under `redis.clients.jedis.search.schemafields.*` — not `redis.clients.jedis.search.*`. Star-importing only `redis.clients.jedis.search.*` will miss them and produce confusing "cannot find symbol `TextField`" errors.
- **Use `SchemaField[]` (the modern API) — not the deprecated `Schema` class.** `Schema sc = new Schema().addTextField(...)` still appears in older test bases and pre-5.0 docs; treat it as legacy. See §14 for the migration.
- **Use `Path2` — not `Path`.** Both exist; `Path2` is the current one for `FT.*` JSON paths and `jsonSet` calls. All upstream examples use `Path2`.


## 5. Create index — HASH

redis-py equivalent: see [`python-redis-py.md#4-create-index--hash`](./python-redis-py.md#4-create-index--hash).

CLI form (from [`index-creation.md`](../index-creation.md)):

```
FT.CREATE idx:bicycle ON HASH PREFIX 1 bicycle:
    SCHEMA
        model        TEXT WEIGHT 2.0
        description  TEXT
        brand        TAG
        condition    TAG
        price        NUMERIC SORTABLE
        store_location GEO
```

Jedis — mirrors `HomeJsonExample.java` STEP_START `make_hash_index` (the upstream HASH-index example; the JSON variant is in §6):

```java
// STEP_START create_index_hash
SchemaField[] schema = {
    TextField.of("model").weight(2.0),
    TextField.of("description"),
    TagField.of("brand"),
    TagField.of("condition"),
    NumericField.of("price").sortable(),
    GeoField.of("store_location")
};

jedis.ftCreate("idx:bicycle",
    FTCreateParams.createParams()
        .on(IndexDataType.HASH)
        .addPrefix("bicycle:"),
    schema
);
// STEP_END
```

HASH-specific notes:

- Field names in the schema are the **hash field names verbatim** — no `$.` path, no `.as("alias")` call. The schema field's name *is* the alias.
- Document keys must literally start with the declared prefix (`bicycle:1`, `bicycle:2`, …). An empty / missing prefix indexes every hash in the database.
- Write documents with `jedis.hset("bicycle:1", Map.of(...))` — indexing happens synchronously on the write.


## 6. Create index — JSON

redis-py equivalent: see [`python-redis-py.md#5-create-index--json`](./python-redis-py.md#5-create-index--json).

CLI form:

```
FT.CREATE idx:bicycle ON JSON PREFIX 1 bicycle:
    SCHEMA
        $.brand        AS brand        TEXT
        $.model        AS model        TEXT
        $.description  AS description  TEXT
        $.price        AS price        NUMERIC
        $.condition    AS condition    TAG
```

Jedis — mirrors `SearchQuickstartExample.java` STEP_START `create_index`:

```java
// STEP_START create_index_json
SchemaField[] schema = {
    TextField.of("$.brand").as("brand"),
    TextField.of("$.model").as("model"),
    TextField.of("$.description").as("description"),
    NumericField.of("$.price").as("price"),
    TagField.of("$.condition").as("condition")
};

jedis.ftCreate("idx:bicycle",
    FTCreateParams.createParams()
        .on(IndexDataType.JSON)
        .addPrefix("bicycle:"),
    schema
);
// STEP_END
```

JSON-specific notes:

- `TextField.of("$.brand")` takes the **JSONPath**, not the alias. Always pair it with `.as("brand")`; the alias is what queries reference as `@brand`.
- Without `.as(...)`, Redis auto-generates an alias from the path — usable but brittle (renaming the JSON key silently breaks the index).
- Array projections: `TextField.of("$.tags[*]").as("tags")`. Nested objects: `TextField.of("$.address.city").as("city")`.
- Add documents with `jedis.jsonSet("bicycle:1", Path2.ROOT_PATH, bicycleJson)` or `jsonSetWithEscape(...)` for a POJO that needs JSON-string-value escaping (used in `SearchQuickstartExample.java` STEP_START `add_documents`).


## 7. FT.SEARCH idioms

redis-py equivalent: see [`python-redis-py.md#6-ftsearch-idioms`](./python-redis-py.md#6-ftsearch-idioms).

For the query DSL itself (delimiters, operators, escaping), read [`../search-syntax-primitives.md`](../search-syntax-primitives.md). This section shows only how Jedis *binds* a query to `FT.SEARCH`.

### Two call shapes

Jedis exposes two overloads:

```java
// String-only — convenient for simple queries.
SearchResult res = jedis.ftSearch("idx:bicycle", "@condition:{new}");

// String + FTSearchParams — the full surface (filters, dialect, sort, return fields, paging).
SearchResult res2 = jedis.ftSearch("idx:bicycle",
    "@condition:{new}",
    FTSearchParams.searchParams()
        .returnFields("brand", "model", "price")
        .sortBy("price", SortingOrder.ASC)
        .limit(0, 10)
        .dialect(2)
);

// Legacy: Query object (still supported; FTSearchParams is the modern path).
Query q = new Query("@condition:{new}").returnFields("brand").dialect(2);
SearchResult res3 = jedis.ftSearch("idx:bicycle", q);
```

`FTSearchParams.searchParams()` is the modern fluent path used across all current upstream examples (`QueryRangeExample.java`, `QueryGeoExample.java`, `QueryEmExample.java`). Use it for new code; the `Query` class still works and is preserved for backward compatibility.

| `FTSearchParams` method | CLI equivalent | Purpose |
|-------------------------|----------------|---------|
| `.limit(offset, num)` | `LIMIT offset num` | Result page slice. |
| `.sortBy(field, SortingOrder.ASC)` | `SORTBY field ASC\|DESC` | Override score-based ranking. Requires the field declared `.sortable()` at index time. |
| `.returnFields(f1, f2, ...)` | `RETURN n f1 f2 ...` | Project only listed fields. |
| `.noContent()` | `NOCONTENT` | IDs only — pair with `LIMIT 0 0` for count-only queries. |
| `.withScores()` | `WITHSCORES` | Append per-doc relevance score. |
| `.verbatim()` | `VERBATIM` | Disable stemming. |
| `.dialect(2)` | `DIALECT 2` | **Always pass this.** |
| `.filter("field", min, max)` | `FILTER field min max` | Inline numeric range; alternative to `@field:[min max]` in the expression. |
| `.addParam("name", value)` | `PARAMS n name value …` | Bind `$name` placeholders in the expression. |

### Exact match (TAG / NUMERIC) — mirrors `QueryEmExample.java`

```java
// STEP_START em1 — numeric exact match via range with equal bounds
SearchResult res1 = jedis.ftSearch("idx:bicycle", "@price:[270 270]");
// Equivalent via FILTER (no inline range):
SearchResult res2 = jedis.ftSearch("idx:bicycle", "*",
    FTSearchParams.searchParams().filter("price", 270, 270));

// STEP_START em2 — tag exact match
SearchResult res3 = jedis.ftSearch("idx:bicycle", "@condition:{new}");

// STEP_START em4 — exact phrase in TEXT
SearchResult res5 = jedis.ftSearch("idx:bicycle", "@description:\"rough terrain\"");
```

### Numeric ranges — mirrors `QueryRangeExample.java`

```java
// STEP_START range1 — inclusive
SearchResult res1 = jedis.ftSearch("idx:bicycle", "@price:[500 1000]",
    FTSearchParams.searchParams().returnFields("price").dialect(2));

// STEP_START range3 — exclusive lower, unbounded upper, via FTSearchParams.filter
SearchResult res3 = jedis.ftSearch("idx:bicycle", "*",
    FTSearchParams.searchParams()
        .returnFields("price")
        .filter("price", 1000, true, Double.POSITIVE_INFINITY, false)
        .dialect(2));

// STEP_START range4 — sorted + paged
SearchResult res4 = jedis.ftSearch("idx:bicycle", "@price:[-inf 2000]",
    FTSearchParams.searchParams()
        .returnFields("price")
        .sortBy("price", SortingOrder.ASC)
        .limit(0, 5)
        .dialect(2));
```

`.filter(field, min, minExclusive, max, maxExclusive)` is Jedis's typed equivalent of `"@price:[(1000 +inf]"`. Pass `Double.POSITIVE_INFINITY` / `Double.NEGATIVE_INFINITY` for unbounded ends.

### Full-text idioms — mirrors `QueryFtExample.java`

```java
// STEP_START ft1 — field-scoped term
SearchResult res1 = jedis.ftSearch("idx:bicycle", "@description: kids");

// STEP_START ft2 — prefix
SearchResult res2 = jedis.ftSearch("idx:bicycle", "@model: ka*");

// STEP_START ft3 — suffix (requires WITHSUFFIXTRIE at index time for efficiency)
SearchResult res3 = jedis.ftSearch("idx:bicycle", "@brand: *bikes");

// STEP_START ft4 — fuzzy (Levenshtein distance 1)
SearchResult res4 = jedis.ftSearch("idx:bicycle", "%optamized%");

// STEP_START ft5 — fuzzy distance 2 (double % per side)
SearchResult res5 = jedis.ftSearch("idx:bicycle", "%%optamised%%");
```

### Geo — mirrors `QueryGeoExample.java`

```java
// STEP_START geo1 — radius query, parameterised
SearchResult res1 = jedis.ftSearch("idx:bicycle",
    "@store_location:[$lon $lat $radius $units]",
    FTSearchParams.searchParams()
        .addParam("lon", -0.1778)
        .addParam("lat", 51.5524)
        .addParam("radius", 20)
        .addParam("units", "mi")
        .dialect(2));

// STEP_START geo2 — GEOSHAPE CONTAINS (requires DIALECT 3)
SearchResult res2 = jedis.ftSearch("idx:bicycle",
    "@pickup_zone:[CONTAINS $bike]",
    FTSearchParams.searchParams()
        .addParam("bike", "POINT(-0.1278 51.5074)")
        .dialect(3));

// STEP_START geo3 — GEOSHAPE WITHIN polygon
SearchResult res3 = jedis.ftSearch("idx:bicycle",
    "@pickup_zone:[WITHIN $europe]",
    FTSearchParams.searchParams()
        .addParam("europe", "POLYGON((-25 35, 40 35, 40 70, -25 70, -25 35))")
        .dialect(3));
```

Note that GEOSHAPE fields need `GeoShapeField.of("$.pickup_zone", GeoShapeField.CoordinateSystem.FLAT).as("pickup_zone")` in the schema (see `QueryGeoExample.java`).

### Reading results

`SearchResult` exposes:

```java
res.getTotalResults();              // server-reported match count (long)
res.getDocuments();                 // List<Document>

for (Document doc : res.getDocuments()) {
    doc.getId();                    // "bicycle:0"
    doc.getScore();                 // double, when .withScores() was set
    doc.getString("brand");         // typed field access
    doc.get("price");               // raw Object value
    doc.hasProperty("price");       // existence check
}
```

For HASH indexes, field values come back as `String`. For JSON indexes without `.returnFields(...)`, Jedis returns the whole JSON document under the `$` property (see `SearchQuickstartExample.java` STEP_START `query_single_term` output comments).


## 8. FT.AGGREGATE idioms

redis-py equivalent: see [`python-redis-py.md#7-ftaggregate-idioms`](./python-redis-py.md#7-ftaggregate-idioms).

For pipeline-stage ordering rules, see [`aggregate-pipeline.md`](../aggregate-pipeline.md). This section shows only the Jedis builder shape.

### The `AggregationBuilder`

`AggregationBuilder("<filter-expression>")` is Jedis's `FT.AGGREGATE` shape, separate from `Query`. Fluent setters map directly to pipeline stages:

| `AggregationBuilder` method | CLI stage |
|-----------------------------|-----------|
| `.load(field1, field2, ...)` | `LOAD n f1 f2 ...` |
| `.apply("<expr>", "alias")` | `APPLY <expr> AS alias` (note: expression first, alias second — opposite of redis-py's keyword form) |
| `.filter("<expr>")` | `FILTER <expr>` |
| `.groupBy("@field", Reducers.X.as("alias"))` | `GROUPBY n field REDUCE ...` |
| `.sortBy(SortedField.asc("@field"))` / `.sortBy(n, SortedField.desc("@field"))` | `SORTBY n <field> ASC\|DESC` |
| `.limit(offset, num)` | `LIMIT offset num` |
| `.cursor(count, maxIdleMs)` | `WITHCURSOR [COUNT n] [MAXIDLE ms]` (see §9) |
| `.dialect(2)` | `DIALECT 2` |

Reducers live in `redis.clients.jedis.search.aggr.Reducers` as static factory methods. Common ones:

| Factory | CLI form |
|---------|----------|
| `Reducers.count()` | `REDUCE COUNT 0` |
| `Reducers.count_distinct("@f")` | `REDUCE COUNT_DISTINCT 1 @f` |
| `Reducers.sum("@f")` | `REDUCE SUM 1 @f` |
| `Reducers.avg("@f")` | `REDUCE AVG 1 @f` |
| `Reducers.min("@f")` / `Reducers.max("@f")` | `REDUCE MIN 1 @f` / `MAX 1 @f` |
| `Reducers.quantile("@f", 0.95)` | `REDUCE QUANTILE 2 @f 0.95` |
| `Reducers.to_list("@f")` | `REDUCE TOLIST 1 @f` |

Every reducer takes `.as("alias")` to set the `AS <alias>` token.

### Worked pipeline — mirrors `QueryAggExample.java`

```java
// STEP_START agg1 — LOAD + APPLY (no grouping)
AggregationResult res1 = jedis.ftAggregate("idx:bicycle",
    new AggregationBuilder("@condition:{new}")
        .load("__key", "price")
        .apply("@price - (@price * 0.1)", "discounted")
        .dialect(2));
// Rows: {__key=bicycle:0, discounted=243, price=270}, ...

// STEP_START agg2 — APPLY + GROUPBY + REDUCE
AggregationResult res2 = jedis.ftAggregate("idx:bicycle",
    new AggregationBuilder("*")
        .load("price")
        .apply("@price<1000", "price_category")
        .groupBy("@condition", Reducers.sum("@price_category").as("num_affordable"))
        .dialect(2));

// STEP_START agg3 — synthesised group key via APPLY
AggregationResult res3 = jedis.ftAggregate("idx:bicycle",
    new AggregationBuilder("*")
        .apply("'bicycle'", "type")
        .groupBy("@type", Reducers.count().as("num_total"))
        .dialect(2));
// Rows: {type=bicycle, num_total=10}

// STEP_START agg4 — GROUPBY + TOLIST
AggregationResult res4 = jedis.ftAggregate("idx:bicycle",
    new AggregationBuilder("*")
        .load("__key")
        .groupBy("@condition", Reducers.to_list("__key").as("bicycles"))
        .dialect(2));
```

Result shape: `AggregationResult.getRows()` returns `List<Row>`. Per row:

```java
Row r = res2.getRows().get(0);
r.getString("condition");       // "new"
r.getLong("num_affordable");    // 3
r.getDouble("avg_price");       // when applicable
r.get("bicycles");              // raw value for TOLIST (ArrayList<String>)
```

**Argument order gotcha:** `.apply(expression, alias)` puts the expression *first*. redis-py uses the opposite order via keyword: `apply(discounted="@price * 0.9")` — keyword *is* the alias. When porting from Python, swap.


## 9. Cursors

redis-py equivalent: see [`python-redis-py.md#8-cursors`](./python-redis-py.md#8-cursors).

For lifecycle rules and when to use cursors, see [`aggregate-cursors.md`](../aggregate-cursors.md).

CLI form:

```
FT.AGGREGATE idx:bicycle "*"
    GROUPBY 1 @brand REDUCE COUNT 0 AS n
    WITHCURSOR COUNT 1000 MAXIDLE 30000
    DIALECT 2

FT.CURSOR READ idx:bicycle <cursor_id> COUNT 1000
FT.CURSOR DEL  idx:bicycle <cursor_id>
```

Jedis — open a cursor (`AggregationCommandsTestBase.java` STEP_START `cursor`):

```java
// STEP_START aggregate_cursor_open
AggregationBuilder ab = new AggregationBuilder("*")
    .groupBy("@brand", Reducers.count().as("n"))
    .sortBy(10, SortedField.desc("@n"))
    .cursor(1000, 30000)            // COUNT 1000, MAXIDLE 30000 ms
    .dialect(2);

AggregationResult page = jedis.ftAggregate("idx:bicycle", ab);
long cursorId = page.getCursorId();
// STEP_END
```

Read subsequent pages:

```java
// STEP_START aggregate_cursor_read
while (cursorId != 0) {             // 0 signals exhausted server-side cursor
    page = jedis.ftCursorRead("idx:bicycle", cursorId, 1000);
    cursorId = page.getCursorId();
    process(page.getRows());
}
// STEP_END
```

Explicit cleanup (release before MAXIDLE):

```java
// STEP_START aggregate_cursor_del
jedis.ftCursorDel("idx:bicycle", cursorId);
// STEP_END
```

**Higher-level helper.** Jedis also exposes `ftAggregateIteration(...)` which encapsulates the cursor loop and exposes `nextBatch()` / `collect(...)`, mirroring `AggregationCommandsTestBase.java` `aggregateIteration` test:

```java
FtAggregateIteration it = jedis.ftAggregateIteration("idx:bicycle", ab);
while (!it.isIterationCompleted()) {
    AggregationResult batch = it.nextBatch();
    process(batch.getRows());
}
```

Use the helper for straightforward "drain to the end" cases; fall back to manual `ftCursorRead` / `ftCursorDel` when you need per-batch flow control or explicit cleanup on cancellation.


## 10. Vector queries

redis-py equivalent: see [`python-redis-py.md#9-vector-queries`](./python-redis-py.md#9-vector-queries).

For query-attribute syntax (`=>[KNN ...]`, `[VECTOR_RANGE ...]`) and pre-filter shape, read [`vector-query.md`](../vector-query.md).

**Note on upstream sourcing.** `VectorSetExample.java` in `redis/jedis/src/test/java/io/redis/examples` demonstrates the Redis **Vector Set** data type (`VADD`, `VSIM`) — a separate feature, **not** FT.* vector indexing. The canonical FT.* vector tests live in `redis/jedis/src/test/java/redis/clients/jedis/commands/unified/search/SearchWithParamsCommandsTestBase.java` (methods `testHNSWVectorSimilarity`, `testFlatVectorSimilarity`, `vectorSearchProfile`). Examples below mirror those.

### Index a vector field

CLI form:

```
FT.CREATE idx:bicycle ON JSON PREFIX 1 bicycle: SCHEMA
    ...
    $.description_embeddings AS vector VECTOR FLAT 6
        TYPE FLOAT32 DIM 1536 DISTANCE_METRIC COSINE
```

Jedis — mirrors `SearchWithParamsCommandsTestBase.java` `testHNSWVectorSimilarity` adapted to the bicycle schema (dim 1536 matches OpenAI `text-embedding-3-small` / `ada-002`):

```java
// STEP_START create_vector_index
import redis.clients.jedis.search.schemafields.VectorField;
import redis.clients.jedis.search.schemafields.VectorField.VectorAlgorithm;

int VECTOR_DIMENSION = 1536;        // match your embedding model

Map<String, Object> vectorAttrs = new HashMap<>();
vectorAttrs.put("TYPE", "FLOAT32");
vectorAttrs.put("DIM", VECTOR_DIMENSION);
vectorAttrs.put("DISTANCE_METRIC", "COSINE");

SchemaField[] schema = {
    TextField.of("$.model").noStem().as("model"),
    TextField.of("$.brand").noStem().as("brand"),
    NumericField.of("$.price").as("price"),
    TagField.of("$.type").as("type"),
    VectorField.builder()
        .fieldName("$.description_embeddings")
        .algorithm(VectorAlgorithm.FLAT)        // or HNSW for ANN
        .attributes(vectorAttrs)
        .build()
        .as("vector")
};

jedis.ftCreate("idx:bicycle",
    FTCreateParams.createParams()
        .on(IndexDataType.JSON)
        .addPrefix("bicycle:"),
    schema);
// STEP_END
```

### Encode the query vector

The de facto pattern — `float[]` → little-endian `byte[]`. Jedis ships a helper: `RediSearchUtil.toByteArray(float[])`:

```java
import redis.clients.jedis.search.RediSearchUtil;

byte[] queryBytes = RediSearchUtil.toByteArray(embedding);   // dim 1536 float[]
```

Equivalent explicit form (mirrors `FTHybridCommandsTestBase.java` `floatArrayToByteArray` and the `redis-py` convention):

```java
static byte[] floatArrayToByteArray(float[] floats) {
    ByteBuffer buf = ByteBuffer.allocate(floats.length * 4).order(ByteOrder.LITTLE_ENDIAN);
    for (float f : floats) buf.putFloat(f);
    return buf.array();
}
```

`FLOAT32` little-endian is the only encoding `redis-py` and Jedis ship with — match this on both index and query side, every time. A `double[]` (or big-endian buffer) silently produces zero hits because per-element byte offsets disagree with the index's `TYPE FLOAT32`.

### KNN — mirrors `SearchWithParamsCommandsTestBase.java` `testHNSWVectorSimilarity`

```java
// STEP_START vector_knn
FTSearchParams searchParams = FTSearchParams.searchParams()
    .addParam("query_vector", queryBytes)
    .sortBy("vector_score", SortingOrder.ASC)
    .returnFields("vector_score", "brand", "model", "description")
    .dialect(2);

SearchResult res = jedis.ftSearch("idx:bicycle",
    "(*)=>[KNN 3 @vector $query_vector AS vector_score]",
    searchParams);
// STEP_END
```

`AS vector_score` aliases the distance field — sort by it and return it just like any other field.

### Pre-filtered KNN — mirrors the `query_combined.py` shape from redis-py

```java
// STEP_START vector_prefilter  (pre-Redis-8.4 hybrid pattern — for native blended ranking see §11)
SearchResult res = jedis.ftSearch("idx:bicycle",
    "(@price:[500 1000] -@condition:{new})=>[KNN 3 @vector $query_vector AS vector_score]",
    FTSearchParams.searchParams()
        .addParam("query_vector", queryBytes)
        .sortBy("vector_score", SortingOrder.ASC)
        .returnFields("vector_score", "brand", "model", "price")
        .dialect(2));
// STEP_END
```

The pre-filter `(@price:[500 1000] -@condition:{new})` is applied **before** the KNN scan — it shrinks the candidate set HNSW/FLAT has to walk. Forgetting it is the most common cause of slow vector queries.

### Range — mirrors `SearchWithParamsCommandsTestBase.java` vector range pattern

```java
// STEP_START vector_range
SearchResult res = jedis.ftSearch("idx:bicycle",
    "@vector:[VECTOR_RANGE $range $query_vector]=>{$YIELD_DISTANCE_AS: vector_score}",
    FTSearchParams.searchParams()
        .addParam("range", 0.55)
        .addParam("query_vector", queryBytes)
        .sortBy("vector_score", SortingOrder.ASC)
        .returnFields("vector_score", "brand", "model", "description")
        .limit(0, 4)
        .dialect(2));
// STEP_END
```

`AS <alias>` (KNN form) and `$YIELD_DISTANCE_AS: <alias>` (RANGE form) are not interchangeable — the syntax differs by query type.

### HNSW tuning per-query

`EF_RUNTIME` is an in-query attribute on the KNN tail:

```java
jedis.ftSearch("idx:bicycle",
    "*=>[KNN 10 @vector $query_vector EF_RUNTIME 200 AS score]",
    FTSearchParams.searchParams().addParam("query_vector", queryBytes).dialect(2));
```

Index-time `EF_CONSTRUCTION` lives in the `VectorField` attributes map and is independent of `EF_RUNTIME`.


## 11. FT.HYBRID

redis-py equivalent: see [`python-redis-py.md#10-fthybrid`](./python-redis-py.md#10-fthybrid).

**Version gate:** `FT.HYBRID` requires Redis ≥ **8.4.0**. On older Redis use the pre-filter + KNN pattern in §10. See [`command-selection.md`](../command-selection.md) for the SEARCH vs AGGREGATE vs HYBRID decision.

**Jedis client gate:** the high-level `ftHybrid` method requires **Jedis 6.x**. Jedis 5.x users must use the `sendCommand` fallback shown at the bottom of this section.

### High-level builder

Jedis 6.x ships a high-level `ftHybrid` method backed by `FTHybridParams.builder()`. Pattern: build a `FTHybridSearchParams` (text leg) + `FTHybridVectorParams` (vector leg), combine with a `Combiners.rrf()` or `Combiners.linear()`, optionally add a `FTHybridPostProcessingParams` for `LOAD` / `GROUPBY` / `APPLY` / `SORTBY` / `FILTER` / `LIMIT` stages. Mirrors `FTHybridCommandsTestBase.java` `testComprehensiveFtHybridWithAllFeatures`:

```java
// STEP_START run_hybrid_query_native
import redis.clients.jedis.search.Combiners;
import redis.clients.jedis.search.Scorers;
import redis.clients.jedis.search.hybrid.*;
import redis.clients.jedis.search.aggr.Group;
import redis.clients.jedis.search.aggr.Reducers;
import redis.clients.jedis.search.aggr.SortedField;
import redis.clients.jedis.search.Apply;
import redis.clients.jedis.search.Filter;
import redis.clients.jedis.search.Limit;

FTHybridPostProcessingParams postProcessing = FTHybridPostProcessingParams.builder()
    .load("price", "brand", "@category")
    .groupBy(new Group("@brand")
        .reduce(Reducers.sum("@price").as("sum"))
        .reduce(Reducers.count().as("count")))
    .apply(Apply.of("@sum * 0.9", "discounted_price"))
    .sortBy(SortedField.asc("@sum"), SortedField.desc("@count"))
    .filter(Filter.of("@sum > 700"))
    .limit(Limit.of(0, 20))
    .build();

FTHybridParams hybridArgs = FTHybridParams.builder()
    .search(FTHybridSearchParams.builder()
        .query("@category:{electronics} smartphone camera")
        .scorer(Scorers.bm25std())
        .scoreAlias("text_score")
        .build())
    .vectorSearch(FTHybridVectorParams.builder()
        .field("@image_embedding")
        .vector("vector")                          // param name, bound below
        .method(FTHybridVectorParams.Knn.of(20).efRuntime(150))
        .filter("(@brand:{apple|samsung|google}) (@price:[500 1500])")
        .scoreAlias("vector_score")
        .build())
    .combine(Combiners.linear().alpha(0.7).beta(0.3).window(25))   // or Combiners.rrf().window(60)
    .postProcessing(postProcessing)
    .param("vector", queryBytes)
    .build();

HybridResult reply = jedis.ftHybrid("idx:products", hybridArgs);

reply.getTotalResults();
reply.getDocuments();             // List<Document>
reply.getExecutionTime();         // server-side timing (double, ms)
reply.getWarnings();
// STEP_END
```

### Combine methods

| Factory | CLI emitted | When to use |
|---------|-------------|-------------|
| `Combiners.rrf()` | `COMBINE RRF count [CONSTANT c] [WINDOW w]` | **Default for blended ranking.** Reciprocal Rank Fusion — rank-based, robust without weight tuning. Knobs: `.window(int)`, `.constant(double)` (typically 60). |
| `Combiners.linear()` | `COMBINE LINEAR count [ALPHA a] [BETA b] [WINDOW w]` | Weighted score blend. Needs `.alpha(double)` / `.beta(double)` tuned to your scorer scales. |

Both expose `.as("alias")` to alias the final combined score.

### Important behaviours

- `ftHybrid` is annotated `@Experimental` in Jedis. Pin your Jedis minor version if you depend on it in production; the builder API may shift between minors.
- `FTHybridSearchParams` and `FTHybridVectorParams` use different builders — the search leg owns the text query and scorer; the vector leg owns the vector field, KNN/range method, optional internal `.filter(...)` (applied before the vector scan), and per-leg `.scoreAlias(...)`.
- `FTHybridVectorParams.Knn.of(int)` sets `K`; chain `.efRuntime(int)` to tune HNSW per query.
- Vector blob is bound by name via the top-level `.param("vector", byte[])` — same `PARAMS`-binding mechanism as FT.SEARCH.
- `FTHybridPostProcessingParams.load(...)`-returned field values may come back as `byte[]` rather than `String` depending on protocol and field type — defensive callers should check with `instanceof` before casting (mirrors the `redis-py` HYBRID gotcha).

### Raw `sendCommand` fallback (Jedis 5.x or features missing from the builder)

For Jedis 5.x callers — or features that have not yet landed in the high-level builder — drop to the **binary** `sendCommand` overload. Encoding the vector through `new String(bytes, ISO_8859_1)` is lossy on RESP3 and corrupts certain byte values; pass the raw `byte[]` to `sendCommand(ProtocolCommand, byte[]...)` instead:

```java
import redis.clients.jedis.search.SearchProtocol.SearchCommand;
import redis.clients.jedis.util.SafeEncoder;

byte[] queryBytes = RediSearchUtil.toByteArray(embedding);   // FLOAT32 little-endian

// UnifiedJedis (parent of RedisClient / JedisPooled) exposes sendCommand(ProtocolCommand, byte[]...).
Object raw = ((UnifiedJedis) jedis).sendCommand(
    SearchCommand.HYBRID,
    SafeEncoder.encode("idx:products"),
    SafeEncoder.encode("SEARCH"),      SafeEncoder.encode("laptop"),
    SafeEncoder.encode("VSIM"),        SafeEncoder.encode("@description_vector"),
                                       SafeEncoder.encode("$query_vec"),
    SafeEncoder.encode("KNN"),         SafeEncoder.encode("2"),
                                       SafeEncoder.encode("K"), SafeEncoder.encode("10"),
    SafeEncoder.encode("COMBINE"),     SafeEncoder.encode("RRF"),
                                       SafeEncoder.encode("2"),
                                       SafeEncoder.encode("WINDOW"), SafeEncoder.encode("100"),
    SafeEncoder.encode("PARAMS"),      SafeEncoder.encode("2"),
                                       SafeEncoder.encode("query_vec"),
                                       queryBytes,                              // raw vector — DO NOT round-trip through String
    SafeEncoder.encode("DIALECT"),     SafeEncoder.encode("2")
);
```

Key points:

- Use `SearchCommand.HYBRID` (`redis.clients.jedis.search.SearchProtocol.SearchCommand`) rather than an ad-hoc `ProtocolCommand` anonymous class — it's the canonical enum and survives upstream renames.
- Use `((UnifiedJedis) jedis).sendCommand(ProtocolCommand, byte[]...)` (the **binary** varargs form, defined on `UnifiedJedis`). The `String...` overload silently UTF-8-encodes its arguments and **mangles vector bytes** on the wire.
- `SafeEncoder.encode(String)` is Jedis's canonical UTF-8 string→`byte[]` helper — use it for every text argument so the wire bytes match what the high-level API would emit.
- The vector `byte[]` is passed in directly; no `new String(queryBytes, ISO_8859_1)` round-trip.

The raw shape mirrors the verified syntax in spec 0001 §5.0a. Use it only when the high-level `ftHybrid` builder lacks a flag you need — and consider opening an issue upstream once you confirm the gap.

Upstream sources: `src/main/java/redis/clients/jedis/search/hybrid/FTHybridParams.java`, `src/main/java/redis/clients/jedis/search/Combiners.java`, `src/test/java/redis/clients/jedis/commands/unified/search/FTHybridCommandsTestBase.java`.


## 12. Debugging

redis-py equivalent: see [`python-redis-py.md#11-debugging`](./python-redis-py.md#11-debugging).

For interpreting `FT.EXPLAIN` and `FT.PROFILE` output, see [`debugging.md`](../debugging.md).

### `FT.EXPLAIN`

```java
// Pass either a Query object or a raw query string.
String plan = jedis.ftExplain("idx:bicycle",
    new Query("(@brand:{Velorim}) @price:[100 500]").dialect(2));
System.out.println(plan);
// INTERSECT {
//   TAG:@brand { Velorim }
//   NUMERIC {100.000000 <= @price <= 500.000000}
// }
```

The output is the server's parse tree — useful for spotting unexpected stemming, tokenization, or operator-precedence surprises.

### `FT.PROFILE`

```java
import redis.clients.jedis.search.FTProfileParams;
import redis.clients.jedis.search.ProfilingInfo;

Map.Entry<SearchResult, ProfilingInfo> reply = jedis.ftProfileSearch("idx:bicycle",
    FTProfileParams.profileParams(),
    "@brand:{Velorim}",
    FTSearchParams.searchParams().dialect(2));

SearchResult result = reply.getKey();
Object profile = reply.getValue().getProfilingInfo();   // shape depends on protocol (RESP2/RESP3)
```

For aggregations:

```java
Map.Entry<AggregationResult, ProfilingInfo> aggReply = jedis.ftProfileAggregate("idx:bicycle",
    FTProfileParams.profileParams(),
    new AggregationBuilder("*").groupBy("@brand", Reducers.count().as("n")).dialect(2));
```

The `ProfilingInfo` payload is protocol-shaped: on RESP3 it's a `Map<String, Object>` with `Shards` / `Coordinator` top-level keys (Redis 8+); on RESP2 it's a nested `List`. Cast accordingly — see `SearchWithParamsCommandsTestBase.java` `vectorSearchProfile` for the pattern.

### `FT.INFO`

```java
Map<String, Object> info = jedis.ftInfo("idx:bicycle");
info.get("index_name");                  // "idx:bicycle"
info.get("num_docs");                    // server-stringified counts; cast as needed
info.get("hash_indexing_failures");      // non-zero = silent dropouts (schema mismatch)
info.get("attributes");                  // List of per-field detail maps
info.get("inverted_sz_mb");              // memory footprint
info.get("indexing");                    // 1 while background scan runs
info.get("percent_indexed");             // 0.0 – 1.0
```

`ftInfo` returns a `Map<String, Object>` because the server's reply mixes scalars, lists, and maps. Treat any numeric you read from it as protocol-dependent: RESP2 typically gives strings, RESP3 typed values. Cast defensively.

Key fields to monitor:

| Key | Why it matters |
|-----|----------------|
| `num_docs` | Docs successfully indexed. |
| `hash_indexing_failures` | **Non-zero means silent dropouts** — usually schema/path mismatches. |
| `inverted_sz_mb` | Inverted-index memory footprint. |
| `indexing` | `1` while a background scan is running. |
| `percent_indexed` | Progress of the background scan. |


## 13. Index management

redis-py equivalent: see [`python-redis-py.md#12-index-management`](./python-redis-py.md#12-index-management).

For semantics (FT.ALTER capacity, alias use cases), see [`index-management.md`](../index-management.md).

### Add fields

```java
jedis.ftAlter("idx:bicycle",
    TagField.of("availability"),
    TextField.of("name").weight(0.5));
```

`ftAlter` accepts a varargs of `SchemaField`. Mirrors `SearchWithParamsCommandsTestBase.java` `alter` test. Subject to `MAXTEXTFIELDS` capacity declared at FT.CREATE time. There is no `FT.ALTER` for removing or retyping a field — drop and recreate the index.

### Aliases (for blue/green index swaps)

```java
jedis.ftAliasAdd("idx:bicycle:active", "idx:bicycle_v2");
jedis.ftAliasUpdate("idx:bicycle:active", "idx:bicycle_v2");    // repoint
jedis.ftAliasDel("idx:bicycle:active");
```

Argument order is **`(alias, indexName)`** — Jedis aliases come first, the underlying index second. Mirrors `SearchWithParamsCommandsTestBase.java` `alias` test. Aliases let application code query a stable name while you build a replacement index behind it.

### Drop the index

```java
// Keep documents, drop only the index
jedis.ftDropIndex("idx:bicycle");

// Drop index AND delete every indexed document (destructive)
jedis.ftDropIndexDD("idx:bicycle");
```

`ftDropIndexDD` is the equivalent of `FT.DROPINDEX ... DD` — gone forever, no undo. The double-D in the name signals "drop the docs too."

### List indexes

```java
Set<String> all = jedis.ftList();
```


## 14. Common errors & version gotchas

redis-py equivalent: see [`python-redis-py.md#13-common-errors--version-gotchas`](./python-redis-py.md#13-common-errors--version-gotchas).

| Symptom | Likely cause | Fix |
|---------|--------------|-----|
| `JedisDataException: unknown command 'FT.CREATE'` (or any other `FT.*`) | Redis < 8.0 without the RediSearch module loaded. | Load the module (`MODULE LOAD /path/to/redisearch.so` or via `loadmodule` in `redis.conf`), or upgrade to Redis ≥ 8.0 where Redis Search is built-in. |
| `JedisDataException: unknown command 'FT.HYBRID'` | Server < 8.4.0. | Upgrade or fall back to pre-filter + KNN via FT.SEARCH (§10). |
| `Syntax error at offset N near KNN` | Missing DIALECT 2. | `FTSearchParams.searchParams().dialect(2)` on every vector query and every modern parser feature. |
| GEOSHAPE WITHIN/CONTAINS returns syntax error | Missing `.dialect(3)`, or server lacks DIALECT 3 support. | Pass `.dialect(3)` explicitly; ensure Redis ≥ 7.2 with GEOSHAPE-capable RediSearch. |
| `JedisDataException: Vector dimension mismatch` | Query vector dim differs from index `DIM`. | Recompute embedding with the same model used at index time; assert `embedding.length == DIM`. |
| Vector query returns 0 hits despite obvious matches | Query vector encoded big-endian or as `double[]`. | Use `RediSearchUtil.toByteArray(float[])` or `ByteBuffer.allocate(n*4).order(LITTLE_ENDIAN).putFloat(...)`. |
| `cannot find symbol: class TextField` | Missing `import redis.clients.jedis.search.schemafields.*;` — `redis.clients.jedis.search.*` does not pull in field types. | Add the `schemafields.*` import explicitly. See §4. |
| `JedisDataException: Index already exists` | `ftCreate` is not "create or replace." | Wrap idempotent setup in try/catch on `JedisDataException`, or `ftDropIndex` first when bootstrapping. |
| JSON paths not matching docs | Document set with `jedis.jsonSet(...)` but index defined `ON HASH` (or vice versa). | Match `IndexDataType` to write path. `ftInfo`'s `hash_indexing_failures > 0` is the signal. |
| `Cannot resolve method 'addTextField'` after upgrade to Jedis 5.x | Code uses deprecated `Schema` class. | Migrate to `SchemaField[]` (see migration below). |
| `Cannot resolve symbol 'Path'` after upgrade | Code uses `redis.clients.jedis.json.Path`. | Switch to `redis.clients.jedis.json.Path2` — current path API for FT.* and JSON commands. |
| Empty `getDocuments()` but non-zero `getTotalResults()` | `.noContent()` was set. | Remove `.noContent()` or call `.returnFields(...)`. |

### `Schema` → `SchemaField[]` migration

Older Jedis code (pre-5.x, or community blog posts) uses the `Schema` class:

```java
// LEGACY — Schema class, do not use in new code.
Schema sc = new Schema()
    .addSortableTextField("name", 1.0)
    .addSortableNumericField("count")
    .addTagField("tags");
jedis.ftCreate(INDEX, IndexOptions.defaultOptions(), sc);
```

Current API:

```java
// MODERN — SchemaField[] + FTCreateParams.
SchemaField[] schema = {
    TextField.of("name").weight(1.0).sortable(),
    NumericField.of("count").sortable(),
    TagField.of("tags")
};
jedis.ftCreate(INDEX, FTCreateParams.createParams(), schema);
```

Translation rules:
- `addTextField(name, weight)` → `TextField.of(name).weight(weight)`
- `addSortableTextField(...)` → `.sortable()` chained
- `addNumericField(name)` → `NumericField.of(name)`
- `addTagField(name)` → `TagField.of(name)`
- `addVectorField(name, algo, attrs)` → `VectorField.builder().fieldName(name).algorithm(algo).attributes(attrs).build()`
- `IndexOptions.defaultOptions()` → `FTCreateParams.createParams()` (then chain `.on(IndexDataType.JSON)`, `.addPrefix(...)`, etc.)

### `Path` vs `Path2`

| Class | Status | Use it |
|-------|--------|--------|
| `redis.clients.jedis.json.Path` | Legacy | No |
| `redis.clients.jedis.json.Path2` | Current | **Yes** — for `jsonSet`, `jsonGet`, `jsonDel`, and any `$.*` paths the FT.* schema references. All upstream examples use `Path2`. |


## 15. Upstream examples index

redis-py equivalent: see [`python-redis-py.md#14-upstream-examples-index`](./python-redis-py.md#14-upstream-examples-index).

Curated index of `STEP_START` labels in `redis/jedis/src/test/java/io/redis/examples/` and the broader Jedis FT.* test suite, so you can fetch the runnable Java source by step name. Step labels match the redis-py reference where the two clients cover the same operation — pair them up to verify cross-language behaviour.

| Step label | Operation | Upstream file |
|------------|-----------|---------------|
| `connect` | `RedisClient.create("localhost", 6379)` | `SearchQuickstartExample.java` |
| `create_index` (bicycle JSON) | JSON schema with TEXT/TAG/NUMERIC + `.as(alias)` | `SearchQuickstartExample.java` |
| `add_documents` | `jsonSetWithEscape(key, bicyclePojo)` | `SearchQuickstartExample.java` |
| `wildcard_query` | `Query("*")` | `SearchQuickstartExample.java` |
| `query_single_term` | `Query("@model:Jigger")` | `SearchQuickstartExample.java` |
| `query_single_term_limit_fields` | `Query("@model:Jigger").returnFields("price")` | `SearchQuickstartExample.java` |
| `query_single_term_and_num_range` | `Query("basic @price:[500 1000]")` | `SearchQuickstartExample.java` |
| `query_exact_matching` | `Query("@brand:\"Noka Bikes\"")` | `SearchQuickstartExample.java` |
| `simple_aggregation` | `AggregationBuilder("*").groupBy(...).count()` | `SearchQuickstartExample.java` |
| `import` | Canonical import block | `HomeJsonExample.java` |
| `make_index` | JSON index for users | `HomeJsonExample.java` |
| `make_hash_index` | HASH index, same fields without `$.` paths | `HomeJsonExample.java` |
| `add_data` | `jedis.jsonSet(key, Path2.ROOT_PATH, doc)` | `HomeJsonExample.java` |
| `query1` | `ftSearch("idx:users", "Paul @age:[30 40]")` | `HomeJsonExample.java` |
| `query2` | `FTSearchParams.searchParams().returnFields("city")` | `HomeJsonExample.java` |
| `query3` | `AggregationBuilder("*").groupBy("@city", Reducers.count().as("count"))` | `HomeJsonExample.java` |
| `em1` | Numeric exact match `@price:[270 270]` + `.filter("price", 270, 270)` | `QueryEmExample.java` |
| `em2` | TAG exact match `@condition:{new}` | `QueryEmExample.java` |
| `em3` | Escaping `@email` via `RediSearchUtil.escapeQuery` | `QueryEmExample.java` |
| `em4` | Exact phrase `@description:"rough terrain"` | `QueryEmExample.java` |
| `ft1`–`ft5` | Field-scoped term, prefix, suffix, fuzzy `%term%`, double-fuzzy `%%term%%` | `QueryFtExample.java` |
| `range1` | Inclusive `@price:[500 1000]` | `QueryRangeExample.java` |
| `range2` | `.filter("price", 500, 1000)` form | `QueryRangeExample.java` |
| `range3` | `.filter("price", 1000, true, +inf, false)` (exclusive lower) | `QueryRangeExample.java` |
| `range4` | Range + `.sortBy(..., ASC).limit(0, 5)` | `QueryRangeExample.java` |
| `geo1` | Geo radius parameterised via `.addParam` | `QueryGeoExample.java` |
| `geo2` | `GEOSHAPE CONTAINS` with `.dialect(3)` | `QueryGeoExample.java` |
| `geo3` | `GEOSHAPE WITHIN` polygon | `QueryGeoExample.java` |
| `agg1` | `LOAD` + `APPLY` (no grouping) | `QueryAggExample.java` |
| `agg2` | `APPLY` + `GROUPBY` + `Reducers.sum` | `QueryAggExample.java` |
| `agg3` | Synthesised group key via `.apply("'bicycle'", "type")` | `QueryAggExample.java` |
| `agg4` | `GROUPBY` + `Reducers.to_list("__key")` | `QueryAggExample.java` |
| `aggregate_cursor_open` (in-doc; pairs with redis-py `aggregate_cursor_open`) | `.cursor(count, maxIdle)` opens the cursor; `getCursorId()` reads it | `AggregationCommandsTestBase.java` (`cursor()` test) |
| `aggregate_cursor_read` (in-doc; pairs with redis-py `aggregate_cursor_read`) | `ftCursorRead(index, cursorId, count)` page loop | `AggregationCommandsTestBase.java` (`cursor()` test) |
| `aggregate_cursor_del` (in-doc; pairs with redis-py `aggregate_cursor_del`) | `ftCursorDel(index, cursorId)` explicit release | `AggregationCommandsTestBase.java` (`cursor()` test) |
| `aggregateIteration` (upstream method name) | `ftAggregateIteration(...)` higher-level loop helper | `AggregationCommandsTestBase.java` |
| `vector_knn` (in-doc; pairs with redis-py `vector_knn`) | `(*)=>[KNN 3 @vector $query_vector AS vector_score]` | `SearchWithParamsCommandsTestBase.java` (`testHNSWVectorSimilarity`) |
| `vector_prefilter` (in-doc; pairs with redis-py `vector_prefilter`) | `(@price:[…] -@condition:{new})=>[KNN 3 @vector $query_vector …]` | `SearchWithParamsCommandsTestBase.java` (`testHNSWVectorSimilarity`) |
| `vector_range` (in-doc; pairs with redis-py `vector_range`) | `@vector:[VECTOR_RANGE $range $query_vector]=>{$YIELD_DISTANCE_AS: …}` | `SearchWithParamsCommandsTestBase.java` |
| `testHNSWVectorSimilarity` | `VectorField.builder().algorithm(HNSW)` + `*=>[KNN 2 @v $vec]` | `SearchWithParamsCommandsTestBase.java` |
| `testFlatVectorSimilarity` | `VectorField.builder().algorithm(FLAT)` + `*=>[KNN 2 @v $vec]` | `SearchWithParamsCommandsTestBase.java` |
| `vectorSearchProfile` | KNN inside `ftProfileSearch` | `SearchWithParamsCommandsTestBase.java` |
| `testComprehensiveFtHybridWithAllFeatures` | Full `ftHybrid` with `linear()` combiner + post-processing pipeline | `FTHybridCommandsTestBase.java` |
| `alter` | `ftAlter(index, TagField.of(...), TextField.of(...).weight(0.5))` | `SearchWithParamsCommandsTestBase.java` |
| `alias` | `ftAliasAdd` / `ftAliasUpdate` / `ftAliasDel` | `SearchWithParamsCommandsTestBase.java` |
| `ftExplain` | `ftExplain(index, new Query(...).dialect(2))` | `SearchWithParamsCommandsTestBase.java` |
| `info` | `ftInfo(index)` returns `Map<String, Object>` | `SearchWithParamsCommandsTestBase.java` |

Examples files live under `https://github.com/redis/jedis/tree/master/src/test/java/io/redis/examples/`. The FT.* test bases (`SearchWithParamsCommandsTestBase`, `AggregationCommandsTestBase`, `FTHybridCommandsTestBase`) live under `https://github.com/redis/jedis/tree/master/src/test/java/redis/clients/jedis/commands/unified/search/`.

# redis-py — Redis Search quick reference

This reference covers the `FT.*` (Redis Search) surface of the raw `redis-py` client. It shows how `redis-py` *expresses* the canonical CLI form — it does not re-explain the query DSL. Read it after a reference that already states *what* to do.

- **Query DSL vocabulary** (delimiters, operators, attributes): [`../search-syntax-primitives.md`](../search-syntax-primitives.md). Do not duplicate that grammar here.
- **Jedis (Java) equivalents** for the same operations: [`java-jedis.md`](./java-jedis.md).
- **RedisVL** is a different SDK (schema-first, semantic-cache, message-history). For RedisVL targets, read [`python-redisvl.md`](./python-redisvl.md) instead; the two are not interchangeable.

Examples below trace to specific files in `redis/redis-py/doctests/` and preserve the upstream `STEP_START`/`STEP_END` labels so you can pair-verify against the runnable source. The shared **Bicycle dataset** (`bicycle:<n>` JSON docs with `brand`, `model`, `description`, `price`, `condition`, `type`, `store_location`, `description_embeddings`) is used throughout.

## Table of contents

1. [Minimum supported versions](#1-minimum-supported-versions)
2. [Connection setup](#2-connection-setup)
3. [Schema imports](#3-schema-imports)
4. [Create index — HASH](#4-create-index--hash)
5. [Create index — JSON](#5-create-index--json)
6. [FT.SEARCH idioms](#6-ftsearch-idioms)
7. [FT.AGGREGATE idioms](#7-ftaggregate-idioms)
8. [Cursors](#8-cursors)
9. [Vector queries](#9-vector-queries)
10. [FT.HYBRID](#10-fthybrid)
11. [Debugging](#11-debugging)
12. [Index management](#12-index-management)
13. [Common errors & version gotchas](#13-common-errors--version-gotchas)
14. [Upstream examples index](#14-upstream-examples-index)


## 1. Minimum supported versions

Jedis equivalent: see [`java-jedis.md#1-minimum-supported-versions`](./java-jedis.md#1-minimum-supported-versions).

| Component | Minimum | Notes |
|-----------|---------|-------|
| `redis-py` | **5.0** | Earlier 4.x releases predate the consolidated `redis.commands.search.*` import paths and lack `IndexType.JSON` ergonomics. |
| `redis-py` (for `HybridQuery`) | **7.1.0** | The `redis.commands.search.hybrid_query` module ships from `redis-py` 7.1.0. Older releases (5.x–7.0.x) lack the `HybridQuery` builder and `index.hybrid_search()`. |
| Redis server (FT.SEARCH / FT.AGGREGATE) | **7.4** | Redis Search ships built-in from Redis 8.0; 7.4 still requires the RediSearch module. |
| Redis server (`FT.HYBRID`) | **8.4.0** | Hard floor. Older Redis returns `unknown command 'FT.HYBRID'`. Fall back to pre-filter + `=>[KNN ...]` via FT.SEARCH. |
| Python | 3.8+ | Type hints in `redis.commands.search.*` assume `typing` from 3.8. |

**DIALECT default:** `redis-py` does **not** set DIALECT on your behalf. Every query in this reference passes `DIALECT 2` explicitly (`.dialect(2)` or as a `Query()` argument) — required for vector attribute syntax (`=>[KNN ...]`) and the modern numeric/tag parser. Redis 8 changed the server default to DIALECT 2, but client-side absence still emits the server's compatibility default for older servers.


## 2. Connection setup

Jedis equivalent: see [`java-jedis.md#2-connection-setup`](./java-jedis.md#2-connection-setup).

The canonical connect, from `doctests/search_quickstart.py` — STEP_START `connect`:

```python
import redis

r = redis.Redis(host="localhost", port=6379, db=0, decode_responses=True)
```

`decode_responses=True` is the right default for `FT.*` work because Search returns field names and string values as bytes by default — every result tuple becomes `b"..."` keys/values otherwise. The case that justifies leaving it `False`:

- **Vector blobs you re-emit unchanged.** Vector data is binary `FLOAT32` bytes; with `decode_responses=True` Redis Search still returns them correctly because the client only decodes RESP simple/bulk strings, but mixing decoded + raw bytes in the same result set is error-prone.

For FT.HYBRID results, field decoding differs — see §10.

Pool reuse (for any non-toy app):

```python
pool = redis.ConnectionPool(host="localhost", port=6379, decode_responses=True, max_connections=32)
r = redis.Redis(connection_pool=pool)
```

Reuse one `Redis()` instance across threads — it's thread-safe via the underlying pool.


## 3. Schema imports

Jedis equivalent: see [`java-jedis.md#3-schema-imports`](./java-jedis.md#3-schema-imports).

`redis-py` splits the Search API across submodules of `redis.commands.search`. The canonical import block, mirroring `doctests/search_quickstart.py` and `search_vss.py`:

```python
from redis.commands.search.field import (
    TextField,
    TagField,
    NumericField,
    GeoField,
    GeoShapeField,
    VectorField,
)
from redis.commands.search.index_definition import IndexDefinition, IndexType
from redis.commands.search.query import Query, NumericFilter
from redis.commands.search.aggregation import AggregateRequest, Cursor
import redis.commands.search.reducers as reducers
```

Notes:

- `index_definition` is the modern path; older code imports from `indexDefinition` (camelCase). Both work in 5.x, but the underscore form is what current upstream doctests use.
- The two query builders are **different classes**: `Query` for `FT.SEARCH`, `AggregateRequest` for `FT.AGGREGATE`. They are not interchangeable and don't share methods. This is the single most common source of confusion when porting from another client.
- `redis.commands.search.reducers` is a *module* of factory functions (`count()`, `sum()`, `avg()`, `tolist()`), not a class — that's why upstream imports it with `as reducers`.


## 4. Create index — HASH

Jedis equivalent: see [`java-jedis.md#4-create-index--hash`](./java-jedis.md#4-create-index--hash).

CLI form (from [`index-creation.md`](../index-creation.md)):

```
FT.CREATE idx:bicycle ON HASH PREFIX 1 bicycle:
    SCHEMA
        model        TEXT WEIGHT 2.0
        description  TEXT
        brand        TAG
        condition    TAG
        price        NUMERIC SORTABLE
        store_location GEO
```

redis-py — mirrors `doctests/home_json.py` STEP_START `make_hash_index` (the upstream HASH index example; `home_json.py` itself is JSON-indexed elsewhere, but this specific step demonstrates the HASH variant):

```python
# STEP_START create_index_hash
schema = (
    TextField("model", weight=2.0),
    TextField("description"),
    TagField("brand"),
    TagField("condition"),
    NumericField("price", sortable=True),
    GeoField("store_location"),
)
r.ft("idx:bicycle").create_index(
    schema,
    definition=IndexDefinition(prefix=["bicycle:"], index_type=IndexType.HASH),
)
# STEP_END
```

HASH-specific notes:

- Field names in the schema are the **hash field names verbatim** (no `$.` path prefix; no `as_name`).
- Document keys must literally start with the declared prefix — `bicycle:1`, `bicycle:2`, … An empty / missing prefix indexes every hash in the database.
- Use `r.hset("bicycle:1", mapping={...})` to add documents; indexing happens synchronously on write.


## 5. Create index — JSON

Jedis equivalent: see [`java-jedis.md#5-create-index--json`](./java-jedis.md#5-create-index--json).

CLI form:

```
FT.CREATE idx:bicycle ON JSON PREFIX 1 bicycle:
    SCHEMA
        $.brand        AS brand        TEXT
        $.model        AS model        TEXT
        $.description  AS description  TEXT
        $.price        AS price        NUMERIC
        $.condition    AS condition    TAG
```

redis-py — mirrors `doctests/search_quickstart.py` STEP_START `create_index` and `home_json.py` STEP_START `make_index`:

```python
# STEP_START create_index_json
schema = (
    TextField("$.brand", as_name="brand"),
    TextField("$.model", as_name="model"),
    TextField("$.description", as_name="description"),
    NumericField("$.price", as_name="price"),
    TagField("$.condition", as_name="condition"),
)
r.ft("idx:bicycle").create_index(
    schema,
    definition=IndexDefinition(prefix=["bicycle:"], index_type=IndexType.JSON),
)
# STEP_END
```

JSON-specific notes:

- The first positional argument is the **JSONPath**, not the alias. Always pair it with `as_name="<alias>"`; the alias is what queries reference as `@<alias>`.
- Without `as_name`, Redis auto-generates a field alias from the path — usable but brittle (renaming the JSON key silently breaks the index).
- Array projections use `[*]`: `TextField("$.tags[*]", as_name="tags")`. Nested objects use the obvious `$.address.city`.
- Add documents with `r.json().set("bicycle:1", "$", {...})` (see `home_json.py` STEP_START `add_data`).


## 6. FT.SEARCH idioms

Jedis equivalent: see [`java-jedis.md#6-ftsearch-idioms`](./java-jedis.md#6-ftsearch-idioms).

For the query DSL itself (delimiters, operators, escaping), read [`../search-syntax-primitives.md`](../search-syntax-primitives.md). This section shows only how `redis-py` *binds* a query to `FT.SEARCH`.

### The `Query` builder

`Query("<expression>")` wraps the query expression. The fluent setters mirror `FT.SEARCH` flags:

| `Query` method | CLI equivalent | Purpose |
|----------------|----------------|---------|
| `.paging(offset, num)` | `LIMIT offset num` | Result page slice. |
| `.sort_by(field, asc=True)` | `SORTBY field ASC|DESC` | Override score-based ranking. Requires `SORTABLE` at index time. |
| `.return_fields(*fields)` | `RETURN n f1 f2 ...` | Project only listed fields. |
| `.return_field(path, as_field=...)` | `RETURN n path AS alias` | JSON projection by path with alias. |
| `.no_content()` | `NOCONTENT` | IDs only — saves bandwidth for `LIMIT 0 0` count queries. |
| `.with_scores()` | `WITHSCORES` | Append relevance score per hit. |
| `.verbatim()` | `VERBATIM` | Disable stemming. |
| `.dialect(2)` | `DIALECT 2` | **Always pass this.** |
| `.add_filter(NumericFilter(...))` | `FILTER field min max` | Inline numeric range; alternative to `@field:[min max]` in the expression. |

### Exact match (TAG / NUMERIC) — mirrors `doctests/query_em.py`

```python
# STEP_START em1 — numeric exact match via range with equal bounds
r.ft("idx:bicycle").search(Query("@price:[270 270]").dialect(2))

# STEP_START em2 — tag exact match
r.ft("idx:bicycle").search(Query("@condition:{new}").dialect(2))

# STEP_START em4 — exact phrase in TEXT
r.ft("idx:bicycle").search(Query('@description:"rough terrain"').dialect(2))
```

### Numeric ranges — mirrors `doctests/query_range.py`

```python
# STEP_START range1 — inclusive
r.ft("idx:bicycle").search(Query("@price:[500 1000]").dialect(2))

# STEP_START range3 — exclusive lower, unbounded upper, via NumericFilter
q = Query("*").add_filter(NumericFilter("price", "(1000", "+inf")).dialect(2)
r.ft("idx:bicycle").search(q)

# STEP_START range4 — sorted + paged
q = Query("@price:[-inf 2000]").sort_by("price").paging(0, 5).dialect(2)
r.ft("idx:bicycle").search(q)
```

`NumericFilter` accepts numeric values or RESP-style strings (`"(1000"` for exclusive, `"+inf"` / `"-inf"`).

### Full-text idioms — mirrors `doctests/query_ft.py`

```python
# STEP_START ft1 — field-scoped term
r.ft("idx:bicycle").search(Query("@description: kids").dialect(2))

# STEP_START ft2 — prefix
r.ft("idx:bicycle").search(Query("@model: ka*").dialect(2))

# STEP_START ft3 — suffix (requires WITHSUFFIXTRIE at index time for efficiency)
r.ft("idx:bicycle").search(Query("@brand: *bikes").dialect(2))

# STEP_START ft4 — fuzzy (Levenshtein distance 1)
r.ft("idx:bicycle").search(Query("%optamized%").dialect(2))
```

### Geo — mirrors `doctests/query_geo.py`

```python
# STEP_START geo1 — radius query, parametrised
params = {"lon": -0.1778, "lat": 51.5524, "radius": 20, "units": "mi"}
q = Query("@store_location:[$lon $lat $radius $units]").dialect(2)
r.ft("idx:bicycle").search(q, query_params=params)

# STEP_START geo2 — GEOSHAPE CONTAINS (requires DIALECT 3)
# DIALECT 3 required for GEOSHAPE WITHIN/CONTAINS predicates (Redis 7.2+ with FT.CREATE GEOSHAPE field).
params = {"bike": "POINT(-0.1278 51.5074)"}
q = Query("@pickup_zone:[CONTAINS $bike]").dialect(3)
r.ft("idx:bicycle").search(q, query_params=params)
```

`query_params` is the redis-py mechanism for binding `$name` placeholders in the query expression — use it for any user-supplied or binary value (vector blobs, geo points, range bounds).

### Reading results

`search()` returns a `Result` with `.total` (server-reported match count) and `.docs` (list of `Document` objects). Each `Document` exposes `id`, `payload`, and one attribute per returned field:

```python
res = r.ft("idx:bicycle").search(Query("@condition:{new}").return_fields("brand", "model", "price").dialect(2))
for doc in res.docs:
    print(doc.id, doc.brand, doc.model, doc.price)
```

When `decode_responses=False`, both attribute names and values come back as bytes — fix it at the connection level, not via per-result decoding.


## 7. FT.AGGREGATE idioms

Jedis equivalent: see [`java-jedis.md#7-ftaggregate-idioms`](./java-jedis.md#7-ftaggregate-idioms).

For pipeline-stage ordering rules, see [`aggregate-pipeline.md`](../aggregate-pipeline.md). This section shows only the `redis-py` builder shape.

### The `AggregateRequest` builder

`AggregateRequest("<filter-expression>")` is a separate class from `Query`. The fluent setters map directly to `FT.AGGREGATE` stages:

| `AggregateRequest` method | CLI stage |
|---------------------------|-----------|
| `.load(*fields)` | `LOAD n f1 f2 ...` |
| `.apply(alias="<expr>")` | `APPLY <expr> AS alias` (keyword form: alias on left) |
| `.filter("<expr>")` | `FILTER <expr>` |
| `.group_by(field_or_list, *reducers)` | `GROUPBY n f1 ... REDUCE ...` |
| `.sort_by(("<field>", "ASC|DESC"))` | `SORTBY n <field> ASC|DESC` |
| `.limit(offset, num)` | `LIMIT offset num` |
| `.cursor(count=<n>, max_idle=<seconds>)` | `WITHCURSOR [COUNT n] [MAXIDLE ms]` (see §8) |
| `.dialect(2)` | `DIALECT 2` |

Reducers live in `redis.commands.search.reducers` as factory functions. Common ones:

| Factory | CLI form |
|---------|----------|
| `reducers.count()` | `REDUCE COUNT 0` |
| `reducers.count_distinct("@f")` | `REDUCE COUNT_DISTINCT 1 @f` |
| `reducers.sum("@f")` | `REDUCE SUM 1 @f` |
| `reducers.avg("@f")` | `REDUCE AVG 1 @f` |
| `reducers.min("@f")` / `reducers.max("@f")` | `REDUCE MIN 1 @f` / `MAX 1 @f` |
| `reducers.quantile("@f", 0.95)` | `REDUCE QUANTILE 2 @f 0.95` |
| `reducers.tolist("@f")` | `REDUCE TOLIST 1 @f` |

Every reducer factory takes `.alias("<name>")` to set the `AS <alias>` token.

### Worked pipeline — mirrors `doctests/query_agg.py`

```python
# STEP_START agg1 — LOAD + APPLY (no grouping)
req = (
    AggregateRequest(query="@condition:{new}")
    .load("__key", "price")
    .apply(discounted="@price - (@price * 0.1)")
    .dialect(2)
)
res = r.ft("idx:bicycle").aggregate(req)
# res.rows -> [['__key', 'bicycle:0', 'price', '270', 'discounted', '243'], ...]

# STEP_START agg2 — APPLY + GROUPBY + REDUCE
req = (
    AggregateRequest(query="*")
    .load("price")
    .apply(price_category="@price<1000")
    .group_by("@condition", reducers.sum("@price_category").alias("num_affordable"))
    .dialect(2)
)
r.ft("idx:bicycle").aggregate(req)

# STEP_START agg3 — synthesised group key via APPLY (mirrors doctests/query_agg.py)
req = (
    AggregateRequest(query="*")
    .apply(type="'bicycle'")
    .group_by("@type", reducers.count().alias("num_total"))
    .dialect(2)
)
r.ft("idx:bicycle").aggregate(req)
# res.rows -> [['type', 'bicycle', 'num_total', '10']]

# STEP_START agg4 — GROUPBY + TOLIST
req = (
    AggregateRequest(query="*")
    .load("__key")
    .group_by("@condition", reducers.tolist("__key").alias("bicycles"))
    .dialect(2)
)
r.ft("idx:bicycle").aggregate(req)
```

Result shape: `AggregateResult` with `.rows` (a list of flat `[key, val, key, val, ...]` lists, mirroring RESP2). Pair adjacent elements yourself or convert via the upstream `pandas` helper in `search_vss.py`.

`.apply()` uses keyword arguments where the **keyword is the alias** and the value is the expression — `apply(discounted="@price * 0.9")` emits `APPLY "@price * 0.9" AS discounted`.


## 8. Cursors

Jedis equivalent: see [`java-jedis.md#8-cursors`](./java-jedis.md#8-cursors).

For lifecycle rules and when to use cursors, see [`aggregate-cursors.md`](../aggregate-cursors.md).

> **API note.** `redis-py` 5.x does not expose standalone `ft().cursor_read()` or `ft().cursor_del()` methods. `FT.CURSOR READ` is invoked by passing a `Cursor` instance back to `ft().aggregate(cursor)`. `FT.CURSOR DEL` requires the raw `r.execute_command("FT.CURSOR", "DEL", index, cursor_id)` path shown below.

CLI form:

```
FT.AGGREGATE idx:bicycle "*"
    GROUPBY 1 @brand REDUCE COUNT 0 AS n
    WITHCURSOR COUNT 1000 MAXIDLE 30000
    DIALECT 2

FT.CURSOR READ idx:bicycle <cursor_id> COUNT 1000
FT.CURSOR DEL  idx:bicycle <cursor_id>
```

redis-py — open a cursor:

```python
# STEP_START aggregate_cursor_open
req = (
    AggregateRequest(query="*")
    .group_by("@brand", reducers.count().alias("n"))
    .cursor(count=1000, max_idle=30.0)   # max_idle is seconds; client converts to ms
    .dialect(2)
)
result = r.ft("idx:bicycle").aggregate(req)
cursor = result.cursor             # redis.commands.search.aggregation.Cursor
first_batch = result.rows
# STEP_END
```

Read the next page by passing the `Cursor` back into `aggregate()`:

```python
# STEP_START aggregate_cursor_read
while cursor.cid != 0:             # cid == 0 signals exhausted server-side cursor
    cursor.count = 1000            # optional: override per-read batch size
    page = r.ft("idx:bicycle").aggregate(cursor)
    cursor = page.cursor
    process(page.rows)
# STEP_END
```

Explicit cleanup (release before MAXIDLE):

```python
# STEP_START aggregate_cursor_del
r.execute_command("FT.CURSOR", "DEL", "idx:bicycle", cursor.cid)
# STEP_END
```

See the API note at the top of this section — `FT.CURSOR DEL` requires `execute_command`; `FT.CURSOR READ` is wrapped via `aggregate(cursor)`.


## 9. Vector queries

Jedis equivalent: see [`java-jedis.md#9-vector-queries`](./java-jedis.md#9-vector-queries).

For query-attribute syntax (`=>[KNN ...]`, `[VECTOR_RANGE ...]`) and pre-filter shape, read [`vector-query.md`](../vector-query.md).

### Index a vector field

CLI form:

```
FT.CREATE idx:bicycle ON JSON PREFIX 1 bicycle: SCHEMA
    ...
    $.description_embeddings AS vector VECTOR FLAT 6
        TYPE FLOAT32 DIM 1536 DISTANCE_METRIC COSINE
```

redis-py — mirrors `doctests/search_vss.py` STEP_START `create_index` (dimension parametrised; use 1536 for OpenAI `text-embedding-3-small` / `ada-002`):

```python
# STEP_START create_vector_index
VECTOR_DIMENSION = 1536            # match your embedding model
schema = (
    TextField("$.model", no_stem=True, as_name="model"),
    TextField("$.brand", no_stem=True, as_name="brand"),
    NumericField("$.price", as_name="price"),
    TagField("$.type", as_name="type"),
    VectorField(
        "$.description_embeddings",
        "FLAT",                    # or "HNSW" for ANN
        {
            "TYPE": "FLOAT32",
            "DIM": VECTOR_DIMENSION,
            "DISTANCE_METRIC": "COSINE",
        },
        as_name="vector",
    ),
)
r.ft("idx:bicycle").create_index(
    schema,
    definition=IndexDefinition(prefix=["bicycle:"], index_type=IndexType.JSON),
)
# STEP_END
```

### Encode the query vector

The de facto pattern (used by every upstream doctest): `numpy.array(...).astype(np.float32).tobytes()`. Mirrors `query_combined.py`:

```python
import numpy as np

def embed_to_bytes(model, text: str) -> bytes:
    return np.array(model.encode(text)).astype(np.float32).tobytes()
```

`FLOAT32` little-endian is the only encoding `redis-py` ships with — match this on both index and query side, every time. A `FLOAT64` array silently produces zero hits because the per-element byte offsets disagree with the index's `TYPE FLOAT32`.

### KNN — mirrors `doctests/search_vss.py` STEP_START `run_knn_query`

```python
# STEP_START vector_knn
query = (
    Query("(*)=>[KNN 3 @vector $query_vector AS vector_score]")
    .sort_by("vector_score")
    .return_fields("vector_score", "id", "brand", "model", "description")
    .dialect(2)
)
res = r.ft("idx:bicycle").search(
    query,
    query_params={"query_vector": embed_to_bytes(model, "Bike for small kids")},
)
# STEP_END
```

### Pre-filtered KNN — mirrors `doctests/query_combined.py` STEP_START `combined7`

```python
# STEP_START vector_prefilter
query = (
    Query("(@price:[500 1000] -@condition:{new})=>[KNN 3 @vector $query_vector AS vector_score]")
    .sort_by("vector_score")
    .return_fields("vector_score", "brand", "model", "price")
    .dialect(2)
)
r.ft("idx:bicycle").search(query, query_params={"query_vector": query_vec})
# STEP_END
```

The pre-filter `(@price:[500 1000] -@condition:{new})` is applied **before** the KNN scan — it shrinks the candidate set HNSW/FLAT has to walk. Forgetting it is the most common cause of slow vector queries.

### Range — mirrors `doctests/search_vss.py` STEP_START `run_range_query`

```python
# STEP_START vector_range
range_query = (
    Query(
        "@vector:[VECTOR_RANGE $range $query_vector]=>"
        "{$YIELD_DISTANCE_AS: vector_score}"
    )
    .sort_by("vector_score")
    .return_fields("vector_score", "brand", "model", "description")
    .paging(0, 4)
    .dialect(2)
)
r.ft("idx:bicycle").search(
    range_query,
    query_params={"range": 0.55, "query_vector": query_vec},
)
# STEP_END
```

`AS <alias>` (KNN form) and `$YIELD_DISTANCE_AS` (RANGE form) are not interchangeable — the upstream doctest demonstrates the difference.

### HNSW tuning per-query

`EF_RUNTIME` is an in-query attribute:

```python
Query("*=>[KNN 10 @vector $query_vector EF_RUNTIME 200 AS score]").dialect(2)
```

Index-time `EF_CONSTRUCTION` is set in the `VectorField` algorithm dict and is independent.


## 10. FT.HYBRID

Jedis equivalent: see [`java-jedis.md#10-fthybrid`](./java-jedis.md#10-fthybrid).

**Version gate:** `FT.HYBRID` requires Redis ≥ **8.4.0** *and* `redis-py` ≥ **7.1.0** (the release that ships the `hybrid_query` module). On older Redis or older `redis-py`, use the pre-filter + KNN pattern in §9. See [`command-selection.md`](../command-selection.md) for the SEARCH vs AGGREGATE vs HYBRID decision.

### High-level builder (recommended)

`redis-py` ≥ **7.1.0** ships an `@experimental` high-level `HybridQuery` builder under `redis.commands.search.hybrid_query`. The shape: build a `HybridSearchQuery` (text leg) + `HybridVsimQuery` (vector leg), combine with a `CombineResultsMethod`, call `index.hybrid_search(...)`.

```python
# STEP_START hybrid_query
from redis.commands.search.hybrid_query import (
    HybridQuery,
    HybridSearchQuery,
    HybridVsimQuery,
    VectorSearchMethods,
    CombineResultsMethod,
    CombinationMethods,
    HybridPostProcessingConfig,
)
# Result types live in a separate module:
from redis.commands.search.hybrid_result import HybridResult, HybridCursorResult

search_leg = HybridSearchQuery(
    query_string="laptop",
    scorer="BM25",
    yield_score_as="text_score",
)
vsim_leg = HybridVsimQuery(
    vector_field_name="@description_vector",
    vector_data="$query_vec",                    # bound via params_substitution below
    vsim_search_method=VectorSearchMethods.KNN,
    vsim_search_method_params={"K": 10, "EF_RUNTIME": 100},
    yield_score_as="vec_score",
)
hybrid = HybridQuery(search_leg, vsim_leg)
combine = CombineResultsMethod(
    CombinationMethods.RRF,                      # or CombinationMethods.LINEAR
    WINDOW=100,
    YIELD_SCORE_AS="final_score",
)
result = r.ft("idx:bicycle").hybrid_search(
    hybrid,
    combine_method=combine,
    params_substitution={"query_vec": embed_to_bytes(model, "laptop")},
    timeout=2000,
)
# STEP_END
```

Returns a `HybridResult` (or `HybridCursorResult` when `cursor=...` is supplied).

### Important behaviours

- `hybrid_search` is decorated `@experimental_method()`. API may shift; pin `redis-py` if you depend on it in production.
- `LOAD`-returned field values come back as **bytes by default**, even with `decode_responses=True`, to match the legacy RESP2 HYBRID contract. Opt into decoding per field via `HybridPostProcessingConfig.load("brand", "model", decode_field=True)` and pass the config as `post_processing=`.
- `CombineResultsMethod` kwargs are **passed verbatim** to the server — `WINDOW`, `CONSTANT`, `YIELD_SCORE_AS` for RRF; `ALPHA`, `BETA`, `YIELD_SCORE_AS` for LINEAR. The client does no validation.

### Raw `execute_command` fallback

When you need a feature not yet wrapped (or are on a redis-py minor that pre-dates the high-level builder), drop to raw RESP:

```python
r.execute_command(
    "FT.HYBRID", "idx:bicycle",
    "SEARCH", "laptop",
    "VSIM", "@description_vector", "$query_vec",
    "KNN", "2", "K", "10",
    "COMBINE", "RRF", "2", "WINDOW", "100",
    "PARAMS", "2", "query_vec", embed_to_bytes(model, "laptop"),
    "DIALECT", "2",
)
```

The raw shape mirrors the verified syntax in spec 0001 §5.0a.

Upstream: `redis/redis-py` master — `redis/commands/search/hybrid_query.py` (builder classes), `redis/commands/search/hybrid_result.py` (`HybridResult`, `HybridCursorResult`), and `redis/commands/search/commands.py` (the `hybrid_search` method). The API is decorated `@experimental_method` and may shift between minor releases — pin `redis-py` if you depend on it.


## 11. Debugging

Jedis equivalent: see [`java-jedis.md#11-debugging`](./java-jedis.md#11-debugging).

For interpreting `FT.EXPLAIN` and `FT.PROFILE` output, see [`debugging.md`](../debugging.md).

### `FT.EXPLAIN`

```python
# Pass either a Query or a raw string
plan = r.ft("idx:bicycle").explain(
    Query("(@brand:{Velorim}) @price:[100 500]").dialect(2)
)
print(plan)
# INTERSECT {
#   TAG:@brand {
#     Velorim
#   }
#   NUMERIC {100.000000 <= @price <= 500.000000}
# }
```

The output is a parse tree — useful for spotting unexpected stemming, tokenization, or operator-precedence surprises.

### `FT.PROFILE`

```python
result, profile_info = r.ft("idx:bicycle").profile(
    Query("@brand:{Velorim}").dialect(2),
    limited=False,
)
print(profile_info.iterators_profile)
print(profile_info.result_processors_profile)
print(profile_info.total_profile_time)
```

`profile()` returns a `(Result, ProfileInformation)` tuple for `Query` input; for `AggregateRequest` it returns `(AggregateResult, ProfileInformation)`. `limited=True` suppresses the per-iterator detail when you only care about totals.

### `FT.INFO`

```python
info = r.ft("idx:bicycle").info()
print(info["num_docs"], info["hash_indexing_failures"], info["inverted_sz_mb"])
```

`info` is a dict-like with stringly-typed values (Redis returns them as strings; cast to int/float as needed). Key fields to monitor:

| Key | Why it matters |
|-----|----------------|
| `num_docs` | Docs successfully indexed. |
| `hash_indexing_failures` | **Non-zero means silent dropouts** — usually schema/path mismatches. |
| `inverted_sz_mb` | Inverted-index memory footprint. |
| `indexing` | `1` while a background scan is running. |
| `percent_indexed` | Progress of the background scan. |


## 12. Index management

Jedis equivalent: see [`java-jedis.md#12-index-management`](./java-jedis.md#12-index-management).

For semantics (FT.ALTER capacity, alias use cases), see [`index-management.md`](../index-management.md).

### Add a field

```python
r.ft("idx:bicycle").alter_schema_add(TagField("availability"))
```

Subject to the `MAXTEXTFIELDS` capacity declared at FT.CREATE time. There is no `FT.ALTER` for removing or retyping a field — drop and recreate the index.

### Aliases (for blue/green index swaps)

```python
r.ft("idx:bicycle_v2").aliasadd("idx:bicycle:active")
r.ft("idx:bicycle_v2").aliasupdate("idx:bicycle:active")   # repoint existing alias
r.ft("idx:bicycle_v2").aliasdel("idx:bicycle:active")
```

All three are wrapped — they call `FT.ALIASADD` / `FT.ALIASUPDATE` / `FT.ALIASDEL` respectively. Aliases let application code query a stable name while you build a replacement index behind it.

### Drop the index

```python
# Keep documents, drop only the index
r.ft("idx:bicycle").dropindex()

# Drop index AND delete every indexed document (destructive)
r.ft("idx:bicycle").dropindex(delete_documents=True)
```

`delete_documents=True` is the equivalent of `FT.DROPINDEX ... DD` — gone forever, no undo.


## 13. Common errors & version gotchas

Jedis equivalent: see [`java-jedis.md#13-common-errors--version-gotchas`](./java-jedis.md#13-common-errors--version-gotchas).

| Symptom | Likely cause | Fix |
|---------|--------------|-----|
| `unknown command 'FT.CREATE'` (or any other `FT.*`) | Redis < 8.0 without the RediSearch module loaded. | Load the module (`MODULE LOAD /path/to/redisearch.so` or via `loadmodule` in `redis.conf`), or upgrade to Redis ≥ 8.0 where Redis Search is built-in. |
| `unknown command 'FT.HYBRID'` | Server < 8.4.0. | Upgrade or fall back to pre-filter + KNN via FT.SEARCH (§9). |
| `ImportError` / `cannot import name 'HybridQuery'` from `redis.commands.search.hybrid_query` | `redis-py` < 7.1.0 — the `hybrid_query` module ships from 7.1.0. | Upgrade `redis-py` to ≥ 7.1.0, or fall back to pre-filter + KNN via FT.SEARCH (§9). |
| `Syntax error at offset N near KNN` | Missing `DIALECT 2`. | Always `.dialect(2)` on every `Query` and `AggregateRequest`. |
| `GEOSHAPE WITHIN/CONTAINS` returns syntax error | Missing `.dialect(3)`, or server lacks DIALECT 3 support. | Pass `.dialect(3)` explicitly; ensure Redis ≥ 7.2 with GEOSHAPE-capable RediSearch. |
| `Vector dimension mismatch` | Query vector dim differs from index `DIM`. | Recompute embedding with the same model used at index time; assert `len(arr) == DIM`. |
| Vector query returns 0 hits despite obvious matches | Query vector encoded as `FLOAT64` (default numpy dtype). | Always `.astype(np.float32)` before `.tobytes()`. |
| Result fields come back as `b"..."` bytes | `decode_responses=False`. | Set `decode_responses=True` on the connection. Don't decode per-result. |
| Result fields come back as bytes inside an FT.HYBRID response | Expected: `HybridResult` LOAD values stay bytes by default. | Pass `HybridPostProcessingConfig().load("brand", decode_field=True)` as `post_processing=`. |
| `Index already exists` from idempotent setup | `create_index` is not "create or replace". | Try/except `ResponseError`, or `dropindex()` first when bootstrapping. |
| `JSON paths` not matching docs | Document set with `JSON.SET` but index defined `ON HASH` (or vice versa). | Match `IndexType` to write path; `info()`'s `hash_indexing_failures` > 0 is the signal. |
| Empty `.docs` but non-zero `.total` | `NOCONTENT` (via `.no_content()`) was set. | Remove `.no_content()` or call `.return_fields(...)`. |
| `'@price:[270]' syntax not yet supported` | Single-value numeric-bracket form is a Redis 8 server feature, but `Query` builder validation may reject it pre-Redis-8 clients. | Use `@price:[270 270]` or `NumericFilter("price", 270, 270)` (mirrors `query_em.py`). |

**DIALECT defaults:** server default is DIALECT 2 from Redis 8; older servers default to 1 and reject the vector attribute form (`=>[KNN ...]`). `redis-py` itself never injects DIALECT — *you* must pass `.dialect(2)`. This is the most common silent failure mode when porting code between Redis versions.


## 14. Upstream examples index

Jedis equivalent: see [`java-jedis.md#14-upstream-examples-index`](./java-jedis.md#14-upstream-examples-index).

Curated index of `STEP_START` labels in `redis/redis-py/doctests/` so you can fetch the runnable source by step name. Files live at `https://github.com/redis/redis-py/blob/master/doctests/<file>`.

| Step label | Operation | Upstream file |
|------------|-----------|---------------|
| `connect` | `redis.Redis(host=..., decode_responses=True)` | `search_quickstart.py` |
| `data_sample` | Bicycle JSON document shape | `search_quickstart.py` |
| `create_index` (bicycle JSON) | JSON schema with TEXT/TAG/NUMERIC + `as_name` aliases | `search_quickstart.py` |
| `make_index` | JSON index for users (TextField/TagField/NumericField) | `home_json.py` |
| `make_hash_index` | HASH index, same fields without `$.` paths | `home_json.py` |
| `add_data` | `r.json().set(key, "$", doc)` | `home_json.py` |
| `query1` | `Query("Paul @age:[30 40]")` — combined TEXT + NUMERIC | `home_json.py` |
| `query2` | `Query("Paul").return_field("$.city", as_field="city")` | `home_json.py` |
| `query3` | `AggregateRequest.group_by("@city", reducers.count().alias("count"))` | `home_json.py` |
| `em1` | Numeric exact match `@price:[270 270]` + `NumericFilter` | `query_em.py` |
| `em2` | TAG exact match `@condition:{new}` | `query_em.py` |
| `em4` | Exact phrase in TEXT | `query_em.py` |
| `range1` | Inclusive numeric range | `query_range.py` |
| `range3` | Exclusive lower bound via `NumericFilter("price", "(1000", "+inf")` | `query_range.py` |
| `range4` | Range + `sort_by("price").paging(0, 5)` | `query_range.py` |
| `ft1`–`ft5` | Field-scoped term, prefix, suffix, fuzzy `%term%`, double-fuzzy `%%term%%` | `query_ft.py` |
| `geo1` | Geo radius with `query_params` substitution | `query_geo.py` |
| `geo2` | `GEOSHAPE` CONTAINS, requires `.dialect(3)` | `query_geo.py` |
| `geo3` | `GEOSHAPE` WITHIN polygon | `query_geo.py` |
| `combined1`–`combined7` | Mixed TAG / NUMERIC / TEXT / negation / KNN pre-filter | `query_combined.py` |
| `agg1` | `LOAD` + `APPLY` (no grouping) | `query_agg.py` |
| `agg2` | `APPLY` + `GROUPBY` + `REDUCE SUM` | `query_agg.py` |
| `agg3` | Synthesised group key via `APPLY type="'bicycle'"` | `query_agg.py` |
| `agg4` | `GROUPBY` + `REDUCE TOLIST` | `query_agg.py` |
| `imports` | Canonical `from redis.commands.search.*` import block | `search_vss.py` |
| `create_index` (vector) | JSON schema with `VectorField("FLAT", {...}, as_name="vector")` for VSS | `search_vss.py` |
| `run_knn_query` | `Query("(*)=>[KNN 3 @vector $query_vector AS vector_score]")` | `search_vss.py` |
| `run_hybrid_query` | Pre-filter + KNN: `(@brand:Peaknetic)=>[KNN ...]` | `search_vss.py` |
| `run_range_query` | `[VECTOR_RANGE $range $query_vector]=>{$YIELD_DISTANCE_AS: ...}` | `search_vss.py` |


### Footer: async

`redis.asyncio.Redis` mirrors the sync API for `FT.*` (same `Query`, `AggregateRequest`, schema imports). Out of scope for v1 of this reference — see `redis-py`'s async tests under `tests/test_asyncio/test_search.py` for parallel examples. Sync semantics described above apply.

# RedisVL — Redis Search quick reference

This reference covers the **search / index / query surface** of RedisVL — the higher-level, schema-first Python SDK that builds on `redis-py`. It shows how RedisVL *expresses* the canonical CLI form via `IndexSchema`, `SearchIndex`, the query classes, and the `FilterExpression` DSL. It does not re-explain the query DSL grammar — that lives in [`../search-syntax-primitives.md`](../search-syntax-primitives.md).

- **redis-py (raw) equivalents** for the same operations: [`python-redis-py.md`](./python-redis-py.md). RedisVL is built on `redis-py`; an `FT.*` command that RedisVL does not wrap is reachable by calling `redis-py` directly through the index's underlying client (see §3). For tasks that are not RedisVL-specific (no schema, no vectorizer, no LLM primitive), prefer the `redis-py` reference.
- **Query DSL vocabulary** (delimiters, operators, escaping): [`../search-syntax-primitives.md`](../search-syntax-primitives.md). RedisVL's `FilterExpression` is a typed builder for that DSL — the grammar itself is not duplicated here.
- **Jedis (Java) equivalents** for cross-language verification of FT.* behaviour: [`java-jedis.md`](./java-jedis.md). RedisVL is Python-only; there is no Java equivalent.

Examples below trace to the upstream **RedisVL user-guide notebooks** under `redis/redis-vl-python/docs/user_guide/`. Each section cites the originating notebook. The shared **Bicycle dataset** is reused where it fits (filters, ranges, RAG-shape examples). For vectorizer demos that need text-embedding-friendly prose, the upstream notebook's small sentence/document dataset is preserved verbatim.

## Table of contents

1. [When to choose RedisVL over raw redis-py](#1-when-to-choose-redisvl-over-raw-redis-py)
2. [Minimum supported versions](#2-minimum-supported-versions)
3. [Connection](#3-connection)
4. [Schema definition — Python dict](#4-schema-definition--python-dict)
5. [Schema definition — YAML](#5-schema-definition--yaml)
6. [Storage type: HASH vs JSON](#6-storage-type-hash-vs-json)
7. [Index lifecycle](#7-index-lifecycle)
8. [FilterExpression DSL](#8-filterexpression-dsl)
9. [Query classes](#9-query-classes)
10. [Vectorizers](#10-vectorizers)
11. [Hybrid retrieval](#11-hybrid-retrieval)
12. [Async](#12-async)
13. [LLM primitives (summary level)](#13-llm-primitives-summary-level)
14. [Common errors & version gotchas](#14-common-errors--version-gotchas)
15. [Upstream examples index](#15-upstream-examples-index)


## 1. When to choose RedisVL over raw redis-py

redis-py equivalent: not applicable — see [`python-redis-py.md`](./python-redis-py.md) when none of the criteria below apply.

| Signal in the task | Pick |
|--------------------|------|
| Schema is declared up front (Python dict or YAML) and the agent is asked to "define an index" | RedisVL |
| Task names a `vectorizer` provider (OpenAI, HuggingFace, Cohere, Vertex, Azure OpenAI, Bedrock, Mistral, VoyageAI) and wants embeddings produced from text | RedisVL |
| Task involves LLM primitives (semantic cache, message history, semantic router) | RedisVL |
| Task is async-first and wants a clean async surface (`AsyncSearchIndex.query`, `.aembed_many`) | RedisVL |
| Task wants the lowest-level control over RESP commands or doesn't involve embeddings at all | raw `redis-py` ([`python-redis-py.md`](./python-redis-py.md)) |
| Task is "use FT.HYBRID directly with custom post-processing the high-level builder doesn't expose" | raw `redis-py` (drop through `index.client`) |
| Task mentions Jedis, Lettuce, node-redis, go-redis, NRedisStack | not RedisVL — RedisVL is Python only |

RedisVL builds on `redis-py`. The two are not mutually exclusive: when an `FT.*` command isn't wrapped at the RedisVL level, the same `SearchIndex` exposes its raw client via the public `index.client` property so an agent can fall through to the `redis-py` patterns described in [`python-redis-py.md`](./python-redis-py.md) without constructing a second connection. (The `index._redis_client` attribute also returns a client but is the internal lazy-init accessor — use `.client` in user code.)


## 2. Minimum supported versions

redis-py equivalent: see [`python-redis-py.md#1-minimum-supported-versions`](./python-redis-py.md#1-minimum-supported-versions).

| Component | Minimum | Notes |
|-----------|---------|-------|
| `redisvl` | **0.18.2** | RedisVL has evolved rapidly; older `0.x` releases predate `HybridQuery`, `AggregateHybridQuery`, `MultiVectorQuery`, and the consolidated `redisvl.extensions.*` import paths used below. Verified against upstream `pyproject.toml` at tag `v0.18.2`. |
| `redis-py` | **5.0** | RedisVL declares `redis>=5.0,<8.0` in its `pyproject.toml`. The library itself is a thin layer over `redis-py`. `HybridQuery` requires `redis-py >= 7.1.0` (the version that ships `FT.HYBRID` support) — see the dedicated row below. |
| `redis-py` (for `HybridQuery`) | **7.1.0** | `HybridQuery` import gates on `redis-py >= 7.1.0` at import time. Older `redis-py` cannot serialise `FT.HYBRID`. |
| Redis server (FT.SEARCH / FT.AGGREGATE) | **7.4** | Redis Search ships built-in from Redis 8.0; 7.4 still requires the RediSearch module. |
| Redis server (`FT.HYBRID` / `HybridQuery`) | **8.4.0** | Hard floor. Older Redis raises `unknown command 'FT.HYBRID'`. Fall back to the pre-filter + KNN pattern via `VectorQuery(filter_expression=...)`. See §11. |
| Python | 3.9+ | RedisVL 0.18 targets 3.9+. |

**DIALECT default:** RedisVL passes `DIALECT 2` on every query by default — every query class accepts a `dialect=` parameter that defaults to `2` (`VectorQuery`, `FilterQuery`, `RangeQuery`, `VectorRangeQuery`, `CountQuery`, `TextQuery`). You do **not** need to set it explicitly. GEOSHAPE `WITHIN`/`CONTAINS` predicates still require manually overriding to `dialect=3`.


## 3. Connection

redis-py equivalent: see [`python-redis-py.md#2-connection-setup`](./python-redis-py.md#2-connection-setup).

Three connection patterns, in order of preference. All three are equivalent in behaviour — pick the one that fits where the connection lives in your application.

```python
from redisvl.index import SearchIndex
from redis import Redis

# (a) Pass a redis-py client. Use this when the connection is managed elsewhere
#     (DI container, app factory, test fixture). Mirrors 01_getting_started.ipynb cell 9.
client = Redis.from_url("redis://localhost:6379")
index = SearchIndex.from_dict(schema, redis_client=client, validate_on_load=True)

# (b) Pass a URL string. RedisVL constructs the client internally. Mirrors cell 11.
index = SearchIndex.from_dict(schema, redis_url="redis://localhost:6379")

# (c) Default — connects to redis://localhost:6379 when neither is set.
index = SearchIndex.from_dict(schema)
```

`from_existing(name, ...)` rehydrates a `SearchIndex` from a server-side index that already exists (the schema is read back via `FT.INFO`):

```python
index = SearchIndex.from_existing("idx:bicycle", redis_url="redis://localhost:6379")
```

`validate_on_load=True` enables schema-shape validation on every `.load()` call — recommended in development, costly in tight write loops.

**Falling through to raw redis-py.** The underlying `redis-py` client is exposed for cases not covered by the high-level API:

```python
raw = index.client                       # SyncRedisClient (a redis.Redis instance)
raw.ft("idx:bicycle").execute_command("FT.SOMETHING", ...)
```

When you reach for `index.client`, switch to [`python-redis-py.md`](./python-redis-py.md) for the idioms.


## 4. Schema definition — Python dict

redis-py equivalent: see [`python-redis-py.md#3-schema-imports`](./python-redis-py.md#3-schema-imports) and `#5-create-index--json`. RedisVL declares the schema once as data; raw `redis-py` passes a tuple of `TextField` / `TagField` / etc. constructors plus an `IndexDefinition`.

The canonical schema shape — mirrors `01_getting_started.ipynb` cell 3:

```python
schema = {
    "index": {
        "name": "user_simple",
        "prefix": "user_simple_docs",
        # "storage_type": "hash" (default) or "json" — see §6
    },
    "fields": [
        {"name": "user",         "type": "tag"},
        {"name": "credit_score", "type": "tag"},
        {"name": "job",          "type": "text"},
        {"name": "age",          "type": "numeric"},
        {
            "name": "user_embedding",
            "type": "vector",
            "attrs": {
                "dims": 3,
                "distance_metric": "cosine",
                "algorithm": "flat",
                "datatype": "float32",
            },
        },
    ],
}
```

The dict goes to `SearchIndex.from_dict(schema)` — see §3 for the connection variants.

**Field types:** `tag`, `text`, `numeric`, `geo`, `vector`. Each maps to the corresponding `FT.CREATE` schema clause.

**Vector field algorithms:** `"flat"` for exact / small-scale (≤ ~1M vectors), `"hnsw"` for ANN, `"svs-vamana"` for SVS Vamana (advanced; Intel-optimised; mention as optional — see `09_svs_vamana.ipynb`).

> The schema above uses 3-dim toy embeddings from the upstream `01_getting_started.ipynb` notebook for brevity; the HNSW attrs block below shows the same schema shape with production-shape 1536 dims. `dims` must match whatever vectorizer or precomputed embedding produces the field's bytes — see §10.

**HNSW attributes** (added under `attrs`):

```python
{
    "name": "embedding",
    "type": "vector",
    "attrs": {
        "dims": 1536,
        "distance_metric": "cosine",
        "algorithm": "hnsw",
        "datatype": "float32",
        "m": 16,                    # max bidirectional links per node
        "ef_construction": 200,     # build-time exploration factor
        "ef_runtime": 10,           # default query-time exploration factor
    },
},
```

**JSON storage with nested paths.** Set `storage_type: "json"` at the index level and use JSONPath-style nested field names (RedisVL emits the path-and-alias for you):

```python
schema = {
    "index": {"name": "bike_index", "prefix": "bike:", "storage_type": "json"},
    "fields": [
        {"name": "name",            "type": "text"},
        {"name": "metadata.brand",  "type": "tag",     "path": "$.metadata.brand"},
        {"name": "metadata.price",  "type": "numeric", "path": "$.metadata.price"},
        # ...
    ],
}
```

The `name` is the query alias (`@metadata.brand`); the `path` is the underlying JSONPath. For top-level JSON fields the `path` defaults to `$.<name>`.


## 5. Schema definition — YAML

redis-py equivalent: not applicable. Raw `redis-py` has no YAML schema concept; you compose fields in code.

YAML is the recommended schema format for production — the file is checked into source control alongside the application and reused across sync/async/CLI consumers. Canonical shape — mirrors `redis/redis-vl-python` upstream `docs/user_guide/schema.yaml`:

```yaml
version: '0.1.0'

index:
  name: vectorizers
  prefix: doc
  storage_type: hash

fields:
  - name: sentence
    type: text
  - name: embedding
    type: vector
    attrs:
      dims: 768
      algorithm: flat
      distance_metric: cosine
```

Load with `from_yaml`:

```python
from redisvl.index import SearchIndex

index = SearchIndex.from_yaml(
    "schemas/bicycle.yaml",
    redis_url="redis://localhost:6379",
    validate_on_load=True,
)
```

Field shape under `fields:` mirrors the dict form in §4 — same `type`, `attrs`, `path`. The top-level `version:` field is the **schema-format** version, not the data version; upstream `docs/user_guide/schema.yaml` at tag `v0.18.2` pins it to `'0.1.0'`. RedisVL validates this format-version string at parse time — keep it `'0.1.0'` for RedisVL 0.18.x and bump only when a future RedisVL release introduces a new schema-format major.


## 6. Storage type: HASH vs JSON

redis-py equivalent: see [`python-redis-py.md#4-create-index--hash`](./python-redis-py.md#4-create-index--hash) and `#5-create-index--json`.

Mirrors `05_hash_vs_json.ipynb`. Set `storage_type` once in the schema; everything else follows.

```python
# HASH storage — default. Each Redis key holds a flat hash; field names are the schema names verbatim.
hash_schema = {
    "index": {"name": "user-hash", "prefix": "user-hash-docs", "storage_type": "hash"},
    "fields": [
        {"name": "user",            "type": "tag"},
        {"name": "office_location", "type": "geo"},
        {"name": "user_embedding",  "type": "vector",
         "attrs": {"dims": 3, "distance_metric": "cosine",
                   "algorithm": "flat", "datatype": "float32"}},
    ],
}
hindex = SearchIndex.from_dict(hash_schema, redis_url="redis://localhost:6379")
hindex.create(overwrite=True)
hindex.storage_type        # -> StorageType.HASH

# JSON storage — same fields, nested JSON document per key. Use JSONPath for nested fields.
json_schema = {
    "index": {"name": "user-json", "prefix": "user-json-docs", "storage_type": "json"},
    "fields": [
        {"name": "user",            "type": "tag"},
        {"name": "office_location", "type": "geo"},
        {"name": "user_embedding",  "type": "vector",
         "attrs": {"dims": 3, "distance_metric": "cosine",
                   "algorithm": "flat", "datatype": "float32"}},
    ],
}
jindex = SearchIndex.from_dict(json_schema, redis_url="redis://localhost:6379")
jindex.create(overwrite=True)
```

**Choosing between them:**

| Trade-off | HASH | JSON |
|-----------|------|------|
| Nested objects (`metadata.brand`) | Flatten yourself before load | Native — use JSONPath in `path:` |
| Partial document update | `HSET key field value` (RedisVL: `.load([{...}])` rewrites) | `JSON.SET key $.path value` |
| Vector encoding at load time | `np.ndarray(...).astype(np.float32).tobytes()` | `[0.1, 0.2, ...]` list (RedisVL converts) |
| Memory footprint per doc | Lower for flat docs | Higher (JSON metadata overhead) |
| Querying nested arrays | Not supported | `$.tags[*]` projections |

When in doubt for AI/RAG workloads, **JSON**: it preserves the natural shape of LLM outputs and allows nested metadata without flattening conventions. HASH wins when documents are already flat key-value structures.


## 7. Index lifecycle

redis-py equivalent: see [`python-redis-py.md#12-index-management`](./python-redis-py.md#12-index-management). RedisVL wraps the same `FT.CREATE` / `FT.DROPINDEX` / `FT.ALTER` / `FT.ALIAS*` commands behind methods on `SearchIndex`.

```python
# Create the index. overwrite=True drops and recreates; drop=True (with overwrite=True)
# also drops every existing indexed document.
index.create(overwrite=True, drop=False)

# Existence + introspection
index.exists()              # -> bool
index.info()                # -> dict from FT.INFO

# Load documents. Returns the list of full Redis keys written.
keys = index.load(data)                          # auto-generates document IDs
keys = index.load(data, id_field="user")         # use a field as the document ID
keys = index.load(data, ttl=3600)                # set per-document TTL

# Fetch by document ID (the unprefixed ID — RedisVL prepends the index prefix).
record = index.fetch("john")

# Delete by full key (with prefix) or by document ID (RedisVL adds the prefix).
index.drop_keys("user_simple_docs:01ABC...")
index.drop_documents("john")
index.drop_documents(["mary", "joe"])

# Clear: delete every indexed document but keep the index.
n_deleted = index.clear()

# Delete the index. drop=True (default) also deletes all indexed documents (FT.DROPINDEX ... DD);
# drop=False keeps the documents and removes only the index definition.
index.delete(drop=True)
```

`index.load(data)` is the bulk-write entry point. It accepts a list of dicts; each dict's keys must match the schema's field names (or the JSON path aliases for JSON-storage schemas). For HASH-storage vector fields the dict value must be `np.ndarray(...).astype(np.float32).tobytes()` (or use a vectorizer, see §10). For JSON-storage vector fields a plain `list[float]` works.

**Updating existing documents.** RedisVL 0.18.2 does **not** expose a dedicated `update_load(...)` method (the name appears in early proposals; it is not in the shipped API). To update existing indexed documents, call `.load(...)` again with explicit `keys=` matching the existing Redis keys, or with the same `id_field` value:

```python
# Re-load the same document IDs. HASH storage merges field-by-field at the Redis
# level (HSET semantics); JSON storage replaces the document.
keys = index.load(updated_data, id_field="user")

# Or write to explicit keys (must be full prefixed keys).
keys = index.load(updated_data, keys=["user_simple_docs:01ABC", "user_simple_docs:01DEF"])
```

The `preprocess=` parameter accepts a callable applied to each item before write — useful for normalising shape or computing derived fields. `validate_on_load=True` (set on the index) re-runs schema validation on every `.load()` call.

`paginate(query, page_size=N)` is the recommended way to walk large result sets without holding everything in memory — yields batches of result dicts:

```python
from redisvl.query import FilterQuery
from redisvl.query.filter import FilterExpression

query = FilterQuery(filter_expression=FilterExpression("*"), return_fields=["user", "age", "job"])
for batch in index.paginate(query, page_size=100):
    for doc in batch:
        process(doc)
```

**Mirrors `01_getting_started.ipynb` cells 13, 18, 23, 26, 28, 30, 32, 33.**


## 8. FilterExpression DSL

redis-py equivalent: see [`python-redis-py.md#6-ftsearch-idioms`](./python-redis-py.md#6-ftsearch-idioms) for raw query strings. The full DSL grammar lives in [`../search-syntax-primitives.md`](../search-syntax-primitives.md); this section shows only how RedisVL's typed `FilterExpression` *compiles to* that grammar.

The four filter classes mirror the four indexable scalar types — `Tag`, `Text`, `Num`, `Geo` — plus `Timestamp` (a `Num` subclass that accepts `datetime` objects). All five live in `redisvl.query.filter`. Operators are overloaded: `==`, `!=`, `<`, `>`, `<=`, `>=`, `%` (text wildcard/fuzzy), `&` (AND), `|` (OR), `~` (NOT — used via `!=`).

### Tag — mirrors `02_complex_filtering.ipynb` cells 8, 10, 12

```python
from redisvl.query.filter import Tag

Tag("credit_score") == "high"                       # @credit_score:{high}
Tag("credit_score") != "high"                       # -@credit_score:{high}
Tag("credit_score") == ["high", "medium"]           # @credit_score:{high|medium}
Tag("credit_score") == set(["high", "medium"])      # same; set enforces uniqueness
Tag("credit_score") == []                           # gracefully -> "*" (no constraint)
```

### Num — mirrors cells 17, 18, 19

```python
from redisvl.query.filter import Num

Num("age").between(15, 35)        # @age:[15 35]
Num("age") == 14                  # @age:[14 14]
Num("age") != 14                  # -@age:[14 14]
Num("age") < 18                   # @age:[-inf (18]
Num("age") >= 18                  # @age:[18 +inf]
```

### Text — mirrors cells 25, 26, 27, 28, 29

```python
from redisvl.query.filter import Text

Text("job") == "doctor"           # @job:"doctor"
Text("job") != "doctor"           # -@job:"doctor"
Text("job") % "doct*"             # @job:doct*  (wildcard / prefix)
Text("job") % "%%engine%%"        # @job:%%engine%%  (fuzzy, Levenshtein 2)
Text("job") % "engineer|doctor"   # @job:(engineer|doctor)
Text("job") % ""                  # gracefully -> "*"
```

### Geo — mirrors cells 34, 35, 36

```python
from redisvl.query.filter import Geo, GeoRadius

Geo("office_location") == GeoRadius(-122.4194, 37.7749, 10, "km")    # @office_location:[-122.4194 37.7749 10 km]
Geo("office_location") != GeoRadius(-122.4194, 37.7749, 10, "km")    # -@office_location:[...]
```

### Timestamp — mirrors cells 21–23

```python
from redisvl.query.filter import Timestamp
from datetime import datetime

dt = datetime(2025, 3, 16, 13, 45, 39)
Timestamp("last_updated") > dt                    # @last_updated:[(<epoch> +inf]
Timestamp("last_updated").between(dt1, dt2)       # @last_updated:[<epoch1> <epoch2>]
```

`Timestamp` converts `datetime` to epoch seconds and emits a `NUMERIC` range — the underlying field must be declared `type: numeric` and stored as epoch seconds.

### Composition — mirrors cells 38, 40, 42

Boolean operators compose any filter into a single expression:

```python
t  = Tag("credit_score") == "high"
lo = Num("age") >= 18
hi = Num("age") <= 100
ts = Timestamp("last_updated") > datetime(2025, 3, 16, 13, 45, 39)

combined = t & lo & hi & ts                       # AND
either   = (Num("age") < 18) | (Num("age") > 93)  # OR

# Defensive composition — empty filters fall back to "*", so partial inputs compose cleanly.
def make_filter(age=None, credit=None, job=None):
    return (
        (Num("age") > age) &
        (Tag("credit_score") == credit) &
        (Text("job") % job)
    )
```

Pass the resulting `FilterExpression` to any query class via `filter_expression=`:

```python
from redisvl.query import VectorQuery

v = VectorQuery(
    vector=[0.1, 0.1, 0.5],
    vector_field_name="user_embedding",
    return_fields=["user", "credit_score", "age", "job", "office_location"],
    filter_expression=combined,
)
```

Or swap the filter on an existing query without rebuilding it:

```python
v.set_filter(Tag("credit_score") != "high")
```

`str(filter_expression)` returns the compiled query string — useful for logging or for verifying what RedisVL emits before sending it to Redis.


## 9. Query classes

redis-py equivalent: see [`python-redis-py.md#6-ftsearch-idioms`](./python-redis-py.md#6-ftsearch-idioms) (FT.SEARCH) and `#7-ftaggregate-idioms` (FT.AGGREGATE). RedisVL's query classes route to either depending on shape.

All seven live under `redisvl.query`. Pass an instance to `index.query(...)` — RedisVL picks the right underlying command:

| Class | Wraps | Use for |
|-------|-------|---------|
| `VectorQuery` | FT.SEARCH with `=>[KNN K @field $vec AS score]` | Top-K nearest neighbours, pre-filterable via `filter_expression=`. |
| `VectorRangeQuery` (also exported as `RangeQuery`) | FT.SEARCH with `=>[VECTOR_RANGE radius $vec]` | All hits within a distance threshold of the query vector. |
| `FilterQuery` | FT.SEARCH on a `FilterExpression` (no vector) | Plain filtered retrieval; pagination via `index.paginate(query, page_size=N)`. |
| `CountQuery` | FT.SEARCH `... LIMIT 0 0` | Count documents matching a filter without fetching them. |
| `TextQuery` | FT.SEARCH with full-text scoring | BM25/TFIDF-scored full-text retrieval over `text` fields. |
| `AggregationQuery` | FT.AGGREGATE | Group-by + reduce pipelines. Inherits from `redis-py`'s `AggregateRequest` — fluent API matches. |
| `HybridQuery` | FT.HYBRID (Redis ≥ 8.4.0) | Native blended text + vector ranking. See §11. |

### VectorQuery — KNN with optional pre-filter

Mirrors `01_getting_started.ipynb` cell 36 + `02_complex_filtering.ipynb` cell 8.

```python
from redisvl.query import VectorQuery
from redisvl.query.filter import Tag, Num

# Top-3 nearest, no filter.
query = VectorQuery(
    vector=[0.1, 0.1, 0.5],
    vector_field_name="user_embedding",
    return_fields=["user", "age", "job", "credit_score", "vector_distance"],
    num_results=3,
)
results = index.query(query)

# Pre-filtered KNN — filter is applied before the vector scan.
query = VectorQuery(
    vector=[0.1, 0.1, 0.5],
    vector_field_name="user_embedding",
    return_fields=["user", "credit_score", "age", "vector_distance"],
    num_results=3,
    filter_expression=(Tag("credit_score") == "high") & (Num("age").between(18, 60)),
)
results = index.query(query)
```

`results` is a `list[dict]` — each dict carries the returned fields plus `id` and (when the vector_distance alias is in `return_fields`) the distance score.

### VectorRangeQuery — within a distance threshold

```python
from redisvl.query import VectorRangeQuery
# Backwards-compatible alias — RangeQuery is a thin subclass kept for older code paths.
from redisvl.query import RangeQuery  # `class RangeQuery(VectorRangeQuery): pass` in redisvl/query/query.py

range_q = VectorRangeQuery(
    vector=[0.1, 0.1, 0.5],
    vector_field_name="user_embedding",
    return_fields=["user", "vector_distance"],
    distance_threshold=0.5,        # COSINE distance in [0, 2]
    num_results=10,                 # cap on returned results
)
results = index.query(range_q)
```

Mirrors `docs/user_guide/11_advanced_queries.ipynb` (distance-threshold pattern; the notebook uses the equivalent `filter_expression` + `VectorQuery` shape rather than `VectorRangeQuery` directly — the class is exercised by `tests/integration/test_query.py`).

### FilterQuery — pure filter retrieval

Mirrors `01_getting_started.ipynb` cell 30.

```python
from redisvl.query import FilterQuery
from redisvl.query.filter import Tag

query = FilterQuery(
    filter_expression=Tag("credit_score") == "high",
    return_fields=["user", "age", "job"],
    num_results=50,
)

# Paginate large result sets — recommended over num_results for full scans.
for batch in index.paginate(query, page_size=100):
    for doc in batch:
        process(doc)
```

### CountQuery — count without fetching

```python
from redisvl.query import CountQuery
from redisvl.query.filter import Tag

count = index.query(CountQuery(filter_expression=Tag("brand") == "Nike"))
# Returns the integer match count; emits FT.SEARCH ... LIMIT 0 0 under the hood.
```

Source: `redisvl.query.CountQuery` (`redisvl/query/query.py` — class at module scope). Exercised by `tests/integration/test_query.py`; the user-guide notebooks favour `FilterQuery` over `CountQuery` for didactic reasons (showing the fetched docs), but the class is a stable part of the v0.18.2 public API.

### TextQuery — full-text scored retrieval

Mirrors `11_advanced_queries.ipynb` cells 8, 10, 13.

```python
from redisvl.query import TextQuery
from redisvl.query.filter import Tag, Num

# Plain text search with BM25STD (default scorer).
text_query = TextQuery(
    text="running shoes",
    text_field_name="brief_description",
    return_fields=["product_id", "brief_description", "category", "price"],
    num_results=5,
)

# Add a filter expression to scope the search.
filtered = TextQuery(
    text="comfortable",
    text_field_name="brief_description",
    filter_expression=Num("price") < 100,
    return_fields=["product_id", "brief_description", "price"],
)

# Multi-field weighting — search across multiple text fields with per-field weights.
weighted = TextQuery(
    text="shoes",
    text_field_name={"brief_description": 1.0, "full_description": 0.5},
    return_fields=["product_id", "brief_description"],
)

# Stopword handling — "english" is the default; pass a custom list or None to disable.
with_stopwords = TextQuery(text="the best shoes", text_field_name="brief_description", stopwords="english")
custom_stop    = TextQuery(text="best shoes", text_field_name="brief_description", stopwords=["for", "with"])
no_stopwords   = TextQuery(text="the best shoes", text_field_name="brief_description", stopwords=None)
```

**Scorers:** `TFIDF`, `TFIDF.DOCNORM`, `BM25STD` (default), `BM25STD.NORM`, `BM25STD.TANH`, `DISMAX`, `DOCSCORE`, `HAMMING`. See `11_advanced_queries.ipynb` cells 10–11.

### AggregationQuery — FT.AGGREGATE shape

`AggregationQuery` lives at `redisvl.query.AggregationQuery` (`redisvl/query/aggregate.py`) and subclasses `redis-py`'s `AggregateRequest`. Its constructor takes a single `query_string` (the FT.AGGREGATE filter expression) and the inherited fluent API matches the one in [`python-redis-py.md#7-ftaggregate-idioms`](./python-redis-py.md#7-ftaggregate-idioms) — `.load()`, `.apply()`, `.group_by()`, `.filter()`, `.sort_by()`, `.limit()`, `.cursor()`.

```python
from redisvl.query import AggregationQuery
from redis.commands.search import reducers

# Top-3 brands by document count, descending — `*` matches all docs.
agg = (
    AggregationQuery("*")
    .group_by("@brand", reducers.count().alias("n"))
    .sort_by(("@n", "DESC"))
    .limit(0, 3)
)
results = index.aggregate(agg)
```

Route through `index.aggregate(...)` when you want the RedisVL result-shape normalisation; the underlying command is FT.AGGREGATE on the index's name. The reducer factories live in `redis.commands.search.reducers` (imported from `redis-py`) — RedisVL does not re-export them. `redisvl/query/aggregate.py` declares only the subclass plus `AggregateHybridQuery`, `MultiVectorQuery`, and `Vector`; the fluent surface is inherited verbatim. The user-guide notebooks (`11_advanced_queries.ipynb`) cover the related `AggregateHybridQuery` (cells 34, 37, 42) but do not include a worked `AggregationQuery` example — see `tests/integration/test_aggregation.py` for executable references.

### SVS Vamana (advanced / optional)

`09_svs_vamana.ipynb` covers Intel's SVS Vamana vector algorithm. Treat it as advanced/optional in v1: it requires a Redis build with SVS support (Intel-optimised) and adds tuning parameters orthogonal to the HNSW/FLAT trade-offs. Declare it via `"algorithm": "svs-vamana"` in the vector field's `attrs`. Most agents should pick FLAT (≤ ~1M vectors) or HNSW (ANN at scale) and only reach for SVS Vamana when explicitly asked.


## 10. Vectorizers

redis-py equivalent: not applicable. Raw `redis-py` has no vectorizer concept — you compute the embedding yourself and pass the raw `bytes` blob into the query (`np.array(...).astype(np.float32).tobytes()`). RedisVL's vectorizers wrap that pattern plus the provider-specific HTTP/SDK call.

### Canonical example — OpenAI

Mirrors `04_vectorizers.ipynb` cells 4–7:

```python
import os
from redisvl.utils.vectorize import OpenAITextVectorizer

oai = OpenAITextVectorizer(
    model="text-embedding-ada-002",                   # or text-embedding-3-small / -3-large
    api_config={"api_key": os.environ["OPENAI_API_KEY"]},
)

# Single embedding.
vec = oai.embed("This is a test sentence.")
print(len(vec))                                       # 1536 for ada-002 / 3-small

# Batch.
sentences = ["That is a happy dog", "That is a happy person", "Today is a sunny day"]
embeddings = oai.embed_many(sentences)

# Async batch — vectorizers expose .aembed_many and .aembed for async use.
embeddings = await oai.aembed_many(sentences)
```

Vectorizers all expose the same surface: `.embed(text)`, `.embed_many(texts)`, `.aembed(text)`, `.aembed_many(texts)`. Pass `as_buffer=True` to `embed_many` to get RedisVL's binary buffer format suitable for direct write into HASH-storage vector fields without the `np.array(...).tobytes()` conversion.

### Provider table

All providers live under `redisvl.utils.vectorize`. Mirrors `redisvl/utils/vectorize/__init__.py`.

| Class | Provider | Auth | Typical default dim | Upstream notebook cell |
|-------|----------|------|---------------------|------------------------|
| `OpenAITextVectorizer` | OpenAI | `api_config={"api_key": ...}` (or `OPENAI_API_KEY`) | 1536 (`ada-002`, `3-small`); 3072 (`3-large`) | `04_vectorizers.ipynb` 4–7 |
| `AzureOpenAITextVectorizer` | Azure OpenAI | `api_config={"api_key", "api_version", "azure_endpoint"}` | Matches deployment | cells 9–11 |
| `HFTextVectorizer` | HuggingFace (local `sentence-transformers`) | None (local model) | Model-dependent (768 for `all-mpnet-base-v2`) | cells 13–14 |
| `VertexAITextVectorizer` (`VertexAIVectorizer`) | Google Vertex AI | `api_config={"project_id", "location", "google_application_credentials"}` | 768 (`text-embedding-005`) | cell 16 |
| `CohereTextVectorizer` | Cohere | `api_config={"api_key": ...}` (or `COHERE_API_KEY`) | 1024 (`embed-english-v3.0`) | cells 18+ |
| `BedrockTextVectorizer` (`BedrockVectorizer`) | AWS Bedrock | AWS credentials via boto3 env / profile | 1024 (`amazon.titan-embed-text-v1`) | bedrock cells |
| `VoyageAITextVectorizer` (`VoyageAIVectorizer`) | VoyageAI | `api_config={"api_key": ...}` | 1024 (`voyage-3`) | voyage cells |
| `MistralAITextVectorizer` | Mistral | `api_config={"api_key": ...}` | 1024 (`mistral-embed`) | — |
| `CustomTextVectorizer` (`CustomVectorizer`) | Your own callable | n/a — you pass a `embed` function | Your model | custom-vectorizer section |

RedisVL vectorizers auto-detect the model's dim on first call for known providers — you only need to set `dims` in the schema when the vectorizer doesn't expose it (e.g., custom). When `dims` in the schema disagrees with what the vectorizer produces, `.load()` raises a dimension-mismatch error at write time.


## 11. Hybrid retrieval

redis-py equivalent: see [`python-redis-py.md#10-fthybrid`](./python-redis-py.md#10-fthybrid). RedisVL exposes the same `FT.HYBRID` surface through `HybridQuery` and `AggregateHybridQuery`.

**Version gate:** `HybridQuery` requires **Redis ≥ 8.4.0** and `redis-py >= 7.1.0`. On older Redis or older `redis-py`, fall back to the **pre-filter + KNN** pattern via `VectorQuery(filter_expression=...)` — see below. The upstream `11_advanced_queries.ipynb` gates every `HybridQuery` example on a `HYBRID_SEARCH_AVAILABLE` flag (cells 32, 36, 39, 41).

### Native FT.HYBRID — `HybridQuery`

Mirrors `11_advanced_queries.ipynb` cell 32:

```python
from redisvl.query import HybridQuery

hybrid_query = HybridQuery(
    text="running shoes",
    text_field_name="brief_description",
    vector=[0.1, 0.2, 0.1],                       # query vector
    vector_field_name="text_embedding",
    return_fields=["product_id", "brief_description", "category", "price"],
    num_results=5,
    yield_text_score_as="text_score",
    yield_vsim_score_as="vector_similarity",
    combination_method="LINEAR",                  # or "RRF" (server default)
    linear_alpha=0.3,                             # 30% text, 70% vector
    yield_combined_score_as="hybrid_score",
)

results = index.query(hybrid_query)
```

**Combination methods:**

- `combination_method="RRF"` — Reciprocal Rank Fusion. Rank-based, robust without weight tuning. Knobs: `rrf_window` (default 20), `rrf_constant` (default 60).
- `combination_method="LINEAR"` — weighted score blend. Knob: `linear_alpha` (text weight; `1 - alpha` is the implicit vector weight).

**Scorers** (text leg): same options as `TextQuery` — `BM25STD` (default), `TFIDF`, `DISMAX`, etc.

**Filter expressions** apply to both legs:

```python
filtered_hybrid = HybridQuery(
    text="professional equipment",
    text_field_name="brief_description",
    vector=[0.9, 0.1, 0.05],
    vector_field_name="text_embedding",
    filter_expression=Num("price") > 100,
    combination_method="LINEAR",
    yield_text_score_as="text_score",
    yield_vsim_score_as="vector_similarity",
    yield_combined_score_as="hybrid_score",
)
```

### Aggregate-shaped hybrid — `AggregateHybridQuery`

When you want the FT.AGGREGATE-shape output (rows, group-by stages) instead of the FT.SEARCH-shape:

```python
from redisvl.query import AggregateHybridQuery

agg_hybrid = AggregateHybridQuery(
    text="running shoes",
    text_field_name="brief_description",
    vector=[0.1, 0.2, 0.1],
    vector_field_name="text_embedding",
    return_fields=["product_id", "brief_description", "category", "price"],
    alpha=0.7,                                    # 70% vector, 30% text
    num_results=5,
)
results = index.query(agg_hybrid)
```

### Fallback for Redis < 8.4.0 — pre-filter + KNN

When `FT.HYBRID` is unavailable, blend retrieval by applying the text filter as a **pre-filter** on the vector query:

```python
from redisvl.query import VectorQuery
from redisvl.query.filter import Text, Num

query = VectorQuery(
    vector=query_vector,
    vector_field_name="text_embedding",
    return_fields=["product_id", "brief_description", "price", "vector_distance"],
    num_results=10,
    # Pre-filter shrinks the candidate set before the KNN scan.
    filter_expression=(Text("brief_description") % "running") & (Num("price") < 200),
)
results = index.query(query)
```

This is **not** the same operation as `FT.HYBRID`: it filters by text but ranks purely by vector distance. Use it when (a) the Redis version doesn't support `FT.HYBRID`, or (b) the workload only needs filtered KNN, not blended ranking. The upstream `02_complex_filtering.ipynb` cell 8 demonstrates the pattern in its native shape.


## 12. Async

redis-py equivalent: see [`python-redis-py.md`](./python-redis-py.md) footer (async out of scope for v1).

`AsyncSearchIndex` mirrors `SearchIndex` method-for-method on the search/index/query surface. Async parity is **at full coverage** for the operations relevant to this reference — `create`, `delete`, `load`, `fetch`, `query`, `paginate` (async generator), `aggregate`, `search`, `clear`, `drop_keys`, `drop_documents`, `expire_keys`, `exists`, `info`, `listall`.

```python
from redisvl.index import AsyncSearchIndex
from redis.asyncio import Redis

client = Redis.from_url("redis://localhost:6379")
index = AsyncSearchIndex.from_dict(schema, redis_client=client)

await index.create(overwrite=True, drop=False)
await index.load(data)

# Same query classes; same construction.
from redisvl.query import VectorQuery
query = VectorQuery(vector=[0.1, 0.1, 0.5], vector_field_name="user_embedding",
                    return_fields=["user", "age"], num_results=3)
results = await index.query(query)

await index.delete(drop=True)
```

Mirrors `01_getting_started.ipynb` cells 41–47.

**Divergences from the sync API:**

- `from_existing(...)` is async on `AsyncSearchIndex` — `await AsyncSearchIndex.from_existing(name, redis_url=...)`. Sync is `SearchIndex.from_existing(name, redis_url=...)`.
- `connect(...)` and `set_client(...)` are async.
- `paginate` is an async generator: `async for batch in index.paginate(query, page_size=N):`.
- No context-manager support equivalent to `SearchIndex.__enter__` / `__exit__` — manage lifetime manually with `await index.disconnect()`.

Vectorizers expose `.aembed(text)` and `.aembed_many(texts)` for the embedding call itself — pair them with `AsyncSearchIndex` for end-to-end async pipelines (see §10).


## 13. LLM primitives (summary level)

Full coverage of the LLM-primitive surface is deferred to a future dedicated spec. The summaries below are intentionally narrow — minimal constructor + the upstream notebook to read for depth. None of these primitives are necessary for the core search/index/query surface this reference covers.

### SemanticCache — semantic prompt → response cache

Mirrors `03_llmcache.ipynb` cell 5.

```python
from redisvl.extensions.cache.llm import SemanticCache
from redisvl.utils.vectorize import HFTextVectorizer

llmcache = SemanticCache(
    name="llmcache",                                              # underlying search index name
    redis_url="redis://localhost:6379",
    distance_threshold=0.1,                                       # cosine distance [0, 2]; lower = stricter
    vectorizer=HFTextVectorizer("redis/langcache-embed-v2"),
)

llmcache.store(prompt="What is the capital of France?", response="Paris")
hit = llmcache.check(prompt="capital city of France?")          # returns cached response on semantic match
```

`filterable_fields=[{"name": "user_id", "type": "tag"}]` partitions the cache by tenant/user. Defer to `03_llmcache.ipynb` for filterable-field semantics, TTLs, and metadata.

**LangCache vs SemanticCache:** `SemanticCache` is the in-process Python class shown above. **LangCache** (`13_langcache_semantic_cache.ipynb`) is a separate Redis-hosted product — a managed semantic-cache service on Redis Cloud. They share a vector-search shape but live in different scopes. For LangCache coverage, fall through to the `redis-semantic-cache` skill (a separate skill in this repo) rather than treating it inline as a RedisVL primitive.

### MessageHistory — durable chat-history with optional semantic recall

Mirrors `07_message_history.ipynb` cells 1, 12.

```python
from redisvl.extensions.message_history import MessageHistory, SemanticMessageHistory

# Plain FIFO chat history.
chat = MessageHistory(name="student tutor")
chat.add_message({"role": "user", "content": "Explain backprop."})
recent = chat.get_recent(top_k=8)

# Vector-recall over the same history — fetches semantically similar past turns.
semantic = SemanticMessageHistory(name="tutor")
semantic.add_messages(recent)
relevant = semantic.get_relevant("How does gradient descent relate to backprop?")
```

Defer to `07_message_history.ipynb` for session tagging, role filtering, TTLs.

### SemanticRouter — route a query to a labelled bucket via vector match

Mirrors `08_semantic_router.ipynb` cells 2, 4.

```python
from redisvl.extensions.router import SemanticRouter, Route
from redisvl.utils.vectorize import HFTextVectorizer

tech = Route(
    name="technology",
    references=["what are the latest advancements in AI?", "tell me about the newest gadgets"],
    metadata={"category": "tech"},
    distance_threshold=0.71,
)

router = SemanticRouter(
    name="topic-router",
    vectorizer=HFTextVectorizer(),
    routes=[tech, ...],
    redis_url="redis://localhost:6379",
    overwrite=True,
)

match = router("what's new in machine learning?")           # -> Route name + score
```

Defer to `08_semantic_router.ipynb` for multi-route disambiguation, `from_dict` / `from_yaml` persistence, and threshold tuning.

### Other extensions (also summary-only)

- **EmbeddingsCache** (`redisvl.extensions.cache.embeddings.EmbeddingsCache`) — cache for `embed()` calls to avoid recomputation. See `10_embeddings_cache.ipynb`.
- **Rerankers** (`redisvl.utils.rerank`) — `HFCrossEncoderReranker`, `CohereReranker`, `VoyageAIReranker` for second-stage cross-encoder reranking after initial vector retrieval. See `06_rerankers.ipynb`.


## 14. Common errors & version gotchas

redis-py equivalent: see [`python-redis-py.md#13-common-errors--version-gotchas`](./python-redis-py.md#13-common-errors--version-gotchas).

| Symptom | Likely cause | Fix |
|---------|--------------|-----|
| `redis.exceptions.ResponseError: unknown command 'FT.HYBRID'` from `HybridQuery` | Redis server < 8.4.0 or `redis-py` < 7.1.0. | Upgrade both, or fall back to pre-filter + `VectorQuery` (§11). |
| `_IMPORT_ERROR_MESSAGE = "Hybrid queries require Redis >= 8.4.0 and redis-py>=7.1.0"` | Importing `HybridQuery` against an older `redis-py`. | Upgrade `redis-py`; gate import on `try`/`except ImportError`. |
| `Vector dimension mismatch` on `.load()` | Vectorizer output dim ≠ schema `dims`. | Set `dims` to match the vectorizer's actual output, or pick a model whose dim matches the schema. |
| `.load()` raises `ValidationError` | `validate_on_load=True` and a doc has wrong shape (missing field, wrong type). | Either fix the doc or set `validate_on_load=False` (test/dev only). |
| Vector query returns 0 hits despite obvious matches | HASH-storage vector field was loaded with a `list[float]` instead of `np.array(...).astype(np.float32).tobytes()`. | For HASH: convert to bytes. For JSON: lists work natively. |
| GEOSHAPE WITHIN/CONTAINS returns syntax error | RedisVL defaults to DIALECT 2; `WITHIN`/`CONTAINS` need DIALECT 3. | Pass `dialect=3` on the query class. |
| `OPENAI_API_KEY` `AuthenticationError` from `OpenAITextVectorizer` | Missing env var or wrong key passed to `api_config`. | Set `OPENAI_API_KEY` in the env, or pass `api_config={"api_key": "..."}` explicitly. |
| `AttributeError: 'SearchIndex' object has no attribute 'X'` after a RedisVL minor upgrade | RedisVL renamed/moved an API between minors (`0.x` is pre-1.0). | Pin RedisVL to a known-good version in `requirements.txt`; check the changelog before upgrading. |
| `ImportError: cannot import name 'HybridQuery' from 'redisvl.query'` | RedisVL < 0.18 (or `redis-py` < 7.1.0 at install time). | Upgrade RedisVL to ≥ 0.18 and `redis-py` to ≥ 7.1.0. |
| `AsyncSearchIndex.from_existing(...)` raises "coroutine was never awaited" | The sync API was used. | `await AsyncSearchIndex.from_existing(...)` — async-side method is a coroutine. |
| `index.query(query)` returns rows where every field is `None` | The dict's `return_fields` was empty AND the index is JSON-storage. | Explicitly pass `return_fields=[...]` — RedisVL doesn't auto-return the full JSON doc. |
| `index.create()` errors `Index already exists` on re-run | `.create()` is not idempotent without `overwrite=True`. | `.create(overwrite=True)` for dev bootstrap; gate on `.exists()` for production. |

**DIALECT defaults:** RedisVL passes `dialect=2` on every query class by default. You do not need to set it. Override to `dialect=3` for GEOSHAPE `WITHIN`/`CONTAINS`. The Redis server default (DIALECT 2 from Redis 8.0+) does not affect RedisVL because RedisVL always sends DIALECT explicitly.

**`rvl` CLI tool:** the `rvl` CLI (`rvl index info`, `rvl stats`, `rvl index list`) is a productivity tool for inspecting indexes from the shell. Deferred from v1 of this reference — agents generating Python code rarely need it. See `cli.ipynb` upstream.


## 15. Upstream examples index

redis-py equivalent: see [`python-redis-py.md#14-upstream-examples-index`](./python-redis-py.md#14-upstream-examples-index).

Curated mapping of operation → notebook + cell. Upstream files live at `https://github.com/redis/redis-vl-python/blob/main/docs/user_guide/<file>`. Source classes live in `redis/redis-vl-python/redisvl/...`.

| Operation | Notebook + cell | Upstream class / method |
|-----------|-----------------|-------------------------|
| Schema dict (`index`, `fields`, `attrs`) | `01_getting_started.ipynb` cell 3 | `IndexSchema.from_dict` (`redisvl/schema/schema.py`) |
| `SearchIndex` construction (client / URL / default) | `01_getting_started.ipynb` cells 9, 11 | `SearchIndex.__init__`, `.from_dict`, `.from_yaml` (`redisvl/index/index.py`) |
| `index.create(overwrite=True)` | cell 13 | `SearchIndex.create` |
| `index.load(data)` | cell 18 | `SearchIndex.load` |
| `index.load(data, id_field="user")` + `index.fetch("john")` | cell 26 | `SearchIndex.load`, `.fetch` |
| `index.key("john")` | cell 28 | `SearchIndex.key` |
| `FilterQuery` + `index.paginate(query, page_size=...)` | cell 30 | `redisvl.query.FilterQuery`, `SearchIndex.paginate` |
| `index.drop_keys` / `.drop_documents` | cells 32–33 | `SearchIndex.drop_keys`, `.drop_documents` |
| `VectorQuery` KNN | cell 36 | `redisvl.query.VectorQuery` |
| `VectorRangeQuery` / `RangeQuery` (distance threshold) | not in user-guide notebooks — see `tests/integration/test_query.py` | `redisvl.query.VectorRangeQuery`, `RangeQuery` (`redisvl/query/query.py`) |
| `CountQuery` (FT.SEARCH ... LIMIT 0 0) | not in user-guide notebooks — see `tests/integration/test_query.py` | `redisvl.query.CountQuery` (`redisvl/query/query.py`) |
| `AggregationQuery` fluent (`.group_by` / `.reduce` / `.sort_by`) | not in user-guide notebooks — see `tests/integration/test_aggregation.py` | `redisvl.query.AggregationQuery` (`redisvl/query/aggregate.py`), inherits `AggregateRequest` from `redis.commands.search.aggregation` |
| `AsyncSearchIndex` + async query | cells 41–47 | `AsyncSearchIndex.__init__`, `.query` |
| Schema mutate: `remove_field` + `add_fields` | cell 45 | `IndexSchema.remove_field`, `.add_fields` |
| `Tag(field) == value` | `02_complex_filtering.ipynb` cell 8 | `redisvl.query.filter.Tag` |
| `Tag != / list / set / empty` | cells 10, 12, 13, 15 | `Tag.__eq__`, `__ne__` |
| `Num.between` / `==` / `!=` | cells 17–19 | `redisvl.query.filter.Num` |
| `Timestamp > / < / .between` | cells 21–23 | `redisvl.query.filter.Timestamp` |
| `Text == / != / %` (wildcard, fuzzy, `engineer|doctor`) | cells 25–29 | `redisvl.query.filter.Text` |
| `Geo == GeoRadius(lon, lat, r, units)` | cells 34–36 | `redisvl.query.filter.Geo`, `GeoRadius` |
| Boolean composition `&`, `\|` | cells 38, 40 | `FilterExpression.__and__`, `__or__` |
| `OpenAITextVectorizer.embed` / `.embed_many` / `.aembed_many` | `04_vectorizers.ipynb` cells 5–7 | `redisvl.utils.vectorize.OpenAITextVectorizer` |
| `AzureOpenAITextVectorizer` setup | cells 9–11 | `redisvl.utils.vectorize.AzureOpenAITextVectorizer` |
| `HFTextVectorizer` (local sentence-transformers) | cells 13–14 | `redisvl.utils.vectorize.HFTextVectorizer` |
| `VertexAIVectorizer` setup | cell 16 | `redisvl.utils.vectorize.VertexAIVectorizer` |
| HASH-storage schema + `.create` | `05_hash_vs_json.ipynb` cells 5–6 | `SearchIndex.from_dict` with `storage_type: hash` |
| JSON-storage schema + `.create` | cells 16–17 | `SearchIndex.from_dict` with `storage_type: json` |
| Bike-data + nested JSON metadata | cells 26–27 | (Bicycle-shaped dataset for downstream RAG examples) |
| `TextQuery` BM25 / TFIDF / weighted / stopwords | `11_advanced_queries.ipynb` cells 8–20 | `redisvl.query.TextQuery` |
| `FilterQuery` for STOPWORDS-0 raw query | cell 26 | `redisvl.query.FilterQuery` |
| `HybridQuery` LINEAR + RRF + filter | cells 32, 36, 39, 41 | `redisvl.query.HybridQuery` |
| `AggregateHybridQuery` | cells 34, 37 | `redisvl.query.AggregateHybridQuery` |
| `SemanticCache` constructor + `.store` / `.check` | `03_llmcache.ipynb` cell 5 | `redisvl.extensions.cache.llm.SemanticCache` |
| `SemanticCache` with `filterable_fields` | cells 41, 45 | `SemanticCache(filterable_fields=[...])` |
| `MessageHistory` / `SemanticMessageHistory` | `07_message_history.ipynb` cells 1, 12 | `redisvl.extensions.message_history.MessageHistory`, `SemanticMessageHistory` |
| `SemanticRouter` + `Route` | `08_semantic_router.ipynb` cells 2, 4 | `redisvl.extensions.router.SemanticRouter`, `Route` |
| `SemanticRouter.from_yaml` | cell 21 | `SemanticRouter.from_yaml` |
| Canonical `schema.yaml` | `docs/user_guide/schema.yaml` | `IndexSchema.from_yaml` |
| SVS Vamana algorithm (advanced) | `09_svs_vamana.ipynb` | `"algorithm": "svs-vamana"` in vector field `attrs` |
| `EmbeddingsCache` | `10_embeddings_cache.ipynb` | `redisvl.extensions.cache.embeddings.EmbeddingsCache` |
| `rvl` CLI (deferred) | `cli.ipynb` | Out of scope for v1 |
| LangCache (Redis-hosted product) | `13_langcache_semantic_cache.ipynb` | Cross-link to the `redis-semantic-cache` skill |