{
"schema_version": 2,
"id": "develop/ai/search-and-query/indexing",
"title": "Indexing",
"url": "https://redis.io/docs/latest/develop/ai/search-and-query/indexing/",
"summary": "How to index and search JSON documents",
"aliases": [
"/develop/interact/search-and-query/indexing",
"/develop/interact/search-and-query/indexing/",
"/interact/search-and-query/indexing/"
],
"tags": [
"docs",
"develop",
"stack",
"oss",
"rs",
"rc",
"oss",
"kubernetes",
"clients"
],
"last_updated": "2026-09-11T15:33:04+01:00",
"children": [
{
"id": "develop/ai/search-and-query/indexing/schema-definition",
"summary": "How to define the schema of an index.",
"title": "Schema definition",
"url": "https://redis.io/docs/latest/develop/ai/search-and-query/indexing/schema-definition/"
},
{
"id": "develop/ai/search-and-query/indexing/field-and-type-options",
"summary": "Available field types and options.",
"title": "Field and type options",
"url": "https://redis.io/docs/latest/develop/ai/search-and-query/indexing/field-and-type-options/"
},
{
"id": "develop/ai/search-and-query/indexing/geoindex",
"summary": "Options for indexing geospatial data",
"title": "Geospatial indexing",
"url": "https://redis.io/docs/latest/develop/ai/search-and-query/indexing/geoindex/"
},
{
"id": "develop/ai/search-and-query/indexing/interactive-demo",
"summary": "Change an index's field types, prefixes, and options, and see what each query finds, with every redis-cli command and reply.",
"title": "Indexing interactive demo",
"url": "https://redis.io/docs/latest/develop/ai/search-and-query/indexing/interactive-demo/"
}
],
"page_type": "content",
"content_hash": "b79c9897579bcd1a640313dc0ee34e9f947cfdb3c17cbf55b80fa8c6b0829059",
"sections": [
{
"id": "overview",
"title": "Overview",
"role": "overview",
"text": "In addition to indexing Redis hashes, Redis Open Source can also index JSON documents."
},
{
"id": "create-index-with-json-schema",
"title": "Create index with JSON schema",
"role": "content",
"text": "When you create an index with the [`FT.CREATE`](https://redis.io/docs/latest/commands/ft.create) command, include the `ON JSON` keyword to index any existing and future JSON documents stored in the database.\n\nTo define the `SCHEMA`, you can provide [JSONPath](https://redis.io/docs/latest/develop/data-types/json/path) expressions.\nThe result of each JSONPath expression is indexed and associated with a logical name called an `attribute` (previously known as a `field`).\nYou can use these attributes in queries.\n\n> [!NOTE]\n> `attribute` is optional for [`FT.CREATE`](https://redis.io/docs/latest/commands/ft.create).\n\nUse the following syntax to create a JSON index:\n\n[code example]\n\nFor example, this command creates an index that indexes the name, description, price, and image vector embedding of each JSON document that represents an inventory item:\n\n[code example]\n\nSee [Index limitations](#index-limitations) for more details about JSON index `SCHEMA` restrictions."
},
{
"id": "add-json-documents",
"title": "Add JSON documents",
"role": "content",
"text": "After you create an index, Redis automatically indexes any existing, modified, or newly created JSON documents stored in the database. For existing documents, indexing runs asynchronously in the background, so it can take some time before the document is available. Modified and newly created documents are indexed synchronously, so the document will be available by the time the add or modify command finishes.\n\nYou can use any JSON write command, such as [`JSON.SET`](https://redis.io/docs/latest/commands/json.set) and [`JSON.ARRAPPEND`](https://redis.io/docs/latest/commands/json.arrappend), to create or modify JSON documents.\n\nThe following examples use these JSON documents to represent individual inventory items.\n\nItem 1 JSON document:\n\n[code example]\n\nItem 2 JSON document:\n\n[code example]\n\nUse [`JSON.SET`](https://redis.io/docs/latest/commands/json.set) to store these documents in the database:\n\n[code example]\n\nBecause indexing is synchronous in this case, the documents will be available on the index as soon as the [`JSON.SET`](https://redis.io/docs/latest/commands/json.set) command returns.\nAny subsequent queries that match the indexed content will return the document."
},
{
"id": "search-the-index",
"title": "Search the index",
"role": "content",
"text": "To search the index for JSON documents, use the [`FT.SEARCH`](https://redis.io/docs/latest/commands/ft.search) command.\nYou can search any attribute defined in the `SCHEMA`.\n\nFor example, use this query to search for items with the word \"earbuds\" in the name:\n\n[code example]\n\nThis query searches for all items that include \"bluetooth\" and \"headphones\" in the description:\n\n[code example]\n\nNow search for Bluetooth headphones with a price less than 70:\n\n[code example]\n\nAnd lastly, search for the Bluetooth headphones that are most similar to an image whose embedding is [1.0, 1.0, 1.0, 1.0]:\n\n[code example]\n\nFor more information about search queries, see [Search query syntax](https://redis.io/docs/latest/develop/ai/search-and-query/advanced-concepts/query_syntax).\n\n> [!NOTE]\n> [`FT.SEARCH`](https://redis.io/docs/latest/commands/ft.search) queries require `attribute` modifiers. Don't use JSONPath expressions in queries because the query parser doesn't fully support them."
},
{
"id": "understanding-tag-field-behavior-hash-versus-json",
"title": "Understanding TAG field behavior: hash versus JSON",
"role": "content",
"text": "TAG fields behave differently depending on whether you're indexing hash or JSON documents. This difference is a common source of confusion."
},
{
"id": "hash-documents",
"title": "Hash documents",
"role": "content",
"text": "[code example]"
},
{
"id": "json-documents",
"title": "JSON documents",
"role": "content",
"text": "[code example]"
},
{
"id": "making-json-documents-behave-like-hash-documents",
"title": "Making JSON documents behave like hash documents",
"role": "content",
"text": "To get hash-like behavior in JSON, explicitly add `SEPARATOR \",\"`:\n\n[code example]"
},
{
"id": "recommended-approach-for-json",
"title": "Recommended approach for JSON",
"role": "content",
"text": "Instead of comma-separated strings, use JSON arrays:\n\n[code example]"
},
{
"id": "index-json-arrays-as-tag",
"title": "Index JSON arrays as TAG",
"role": "content",
"text": "For JSON documents, you have two approaches to create TAG fields with multiple values:"
},
{
"id": "approach-1-json-arrays-recommended",
"title": "Approach 1: JSON arrays (recommended)",
"role": "content",
"text": "The preferred method for indexing multiple tag values is using JSON arrays. Each array element becomes a separate tag value. Use the [JSONPath](https://redis.io/docs/latest/develop/data-types/json/path) wildcard operator `[*]` to index array elements.\n\n[code example]\n\nNow you can search for silver headphones:\n\n[code example]"
},
{
"id": "approach-2-strings-with-explicit-separators",
"title": "Approach 2: strings with explicit separators",
"role": "content",
"text": "You can also use comma-separated strings, but you must explicitly specify the `SEPARATOR`:\n\n[code example]\n\n> [!NOTE] Important: JSON vs HASH behavior\n> - **JSON without SEPARATOR**: `\"black,silver\"` becomes one tag: `\"black,silver\"`.\n> - **JSON with SEPARATOR \",\"**: `\"black,silver\"` becomes two tags: `\"black\"` and `\"silver\"`.\n> - **Hash (default)**: `\"black,silver\"` becomes two tags: `\"black\"` and `\"silver\"`.\n>\n> For JSON, always specify `SEPARATOR \",\"` if you want to split comma-separated strings, or use arrays instead."
},
{
"id": "which-approach-to-choose",
"title": "Which approach to choose?",
"role": "content",
"text": "Use JSON arrays when:\n\n- You control the data structure.\n- You want clean, structured data.\n- You need to store complex values (strings with spaces, punctuation).\n\nUse strings with separators when:\n\n- You're migrating from hashes to JSON.\n- You receive data as delimited strings.\n- You need compatibility with existing systems."
},
{
"id": "index-json-arrays-as-text",
"title": "Index JSON arrays as TEXT",
"role": "content",
"text": "Starting with RediSearch v2.6.0, full text search can be done on an array of strings or on a JSONPath leading to multiple strings.\n\nIf you want to index multiple string values as TEXT, use either a JSONPath leading to a single array of strings, or a JSONPath leading to multiple string values, using JSONPath operators such as wildcard, filter, union, array slice, and/or recursive descent.\n\nTo index an item's list of available colors, specify the JSONPath `$.colors` in the `SCHEMA` definition during index creation:\n\n[code example]\n\n[code example]\n\nNow you can do full text search for light colored headphones:\n\n[code example]"
},
{
"id": "limitations",
"title": "Limitations",
"role": "limits",
"text": "- When a JSONPath may lead to multiple values and not only to a single array, e.g., when a JSONPath contains wildcards, etc., specifying `SLOP` or `INORDER` in [`FT.SEARCH`](https://redis.io/docs/latest/commands/ft.search) will return an error, since the order of the values matching the JSONPath is not well defined, leading to potentially inconsistent results.\n\n For example, using a JSONPath such as `$..b[*]` on a JSON value such as\n [code example]\n may match values in various orderings, depending on the specific implementation of the JSONPath library being used.\n\n Since `SLOP` and `INORDER` consider relative ordering among the indexed values, and results may change in future releases, an error will be returned.\n\n- When JSONPath leads to multiple values:\n - String values are indexed\n - `null` values are skipped\n - Any other value type will cause an indexing failure"
},
{
"id": "handling-phrases-in-different-array-slots",
"title": "Handling phrases in different array slots:",
"role": "content",
"text": "When indexing, a predefined delta is used to increase positional offsets between array slots for multiple text values. This delta controls the level of separation between phrases in different array slots (related to the `SLOP` parameter of [`FT.SEARCH`](https://redis.io/docs/latest/commands/ft.search)).\nThis predefined value is set by the configuration parameter `MULTI_TEXT_SLOP` (at module load-time). The default value is 100."
},
{
"id": "index-json-arrays-as-numeric",
"title": "Index JSON arrays as NUMERIC",
"role": "content",
"text": "Starting with RediSearch v2.6.1, search can be done on an array of numerical values or on a JSONPath leading to multiple numerical values.\n\nIf you want to index multiple numerical values as NUMERIC, use either a JSONPath leading to a single array of numbers, or a JSONPath leading to multiple numbers, using JSONPath operators such as wildcard, filter, union, array slice, and/or recursive descent.\n\nFor example, add to the item's list the available `max_level` of volume (in decibels):\n\n[code example]\n\nTo index the `max_level` array, specify the JSONPath `$.max_level` in the `SCHEMA` definition during index creation:\n\n[code example]\n\nYou can now search for headphones with specific max volume levels, for example, between 70 and 80 (inclusive), returning items with at least one value in their `max_level` array, which is in the requested range:\n\n[code example]\n\nYou can also search for items with all values in a specific range. For example, all values are in the range [90, 120] (inclusive):\n\n[code example]"
},
{
"id": "limitations-1",
"title": "Limitations",
"role": "limits",
"text": "When JSONPath leads to multiple numerical values:\n - Numerical values are indexed\n - `null` values are skipped\n - Any other value type will cause an indexing failure"
},
{
"id": "index-json-arrays-as-geo-and-geoshape",
"title": "Index JSON arrays as GEO and GEOSHAPE",
"role": "content",
"text": "You can use `GEO` and `GEOSHAPE` fields to store geospatial data,\nsuch as geographical locations and geometric shapes. See\n[Geospatial indexing](https://redis.io/docs/latest/develop/ai/search-and-query/indexing/geoindex)\nto learn how to use these schema types and see the\n[Geospatial](https://redis.io/docs/latest/develop/ai/search-and-query/advanced-concepts/geo)\nreference page for an introduction to their format and usage."
},
{
"id": "index-json-arrays-as-vector",
"title": "Index JSON arrays as VECTOR",
"role": "content",
"text": "Starting with RediSearch 2.6.0, you can index a JSONPath leading to an array of numeric values as a VECTOR type in the index schema.\n\nFor example, assume that your JSON items include an array of vector embeddings, where each vector represents an image of a product. To index these vectors, specify the JSONPath `$.embedding` in the schema definition during index creation:\n\n[code example]\n\nNow you can search for the two headphones that are most similar to the image embedding by using vector search KNN query. (Note that the vector queries are supported as of dialect 2.) For example:\n\n[code example]\n\nIf you want to index multiple numeric arrays as VECTOR, use a [JSONPath](https://redis.io/docs/latest/develop/data-types/json/path) leading to multiple numeric arrays using JSONPath operators such as wildcard, filter, union, array slice, and/or recursive descent.\n\nFor example, assume that your JSON items include an array of vector embeddings, where each vector represents a different image of the same product. To index these vectors, specify the JSONPath `$.embeddings[*]` in the schema definition during index creation:\n\n[code example]\n\n> [!NOTE] Important note\n> Unlike the case with the NUMERIC type, setting a static path such as `$.embedding` in the schema for the VECTOR type does not allow you to index multiple vectors stored under that field. Hence, if you set `$.embedding` as the path to the index schema, specifying an array of vectors in the `embedding` field in your JSON will cause an indexing failure.\n\nNow you can search for the two headphones that are most similar to an image embedding by using vector search KNN query. (Note that the vector queries are supported as of dialect 2.) The distance between a document to the query vector is defined as the minimum distance between the query vector to a vector that matches the JSONPath specified in the schema. For example:\n\n[code example]\nNote that `0.771500051022` is the L2 distance between the query vector and `[-0.8,-0.15,0.33,-0.01]`, which is the second element in the embedding array, and it is lower than the L2 distance between the query vector and `[-0.7,-0.51,0.88,0.14]`, which is the first element in the embedding array.\n\nFor more information on vector similarity syntax, see [Vector fields](https://redis.io/docs/latest/develop/ai/search-and-query/vectors)."
},
{
"id": "index-json-objects",
"title": "Index JSON objects",
"role": "content",
"text": "You cannot index JSON objects. FT.CREATE will return an error if the JSONPath expression returns an object.\n\nTo index the contents of a JSON object, you need to index the individual elements within the object in separate attributes.\n\nFor example, to index the `connection` JSON object, define the `$.connection.wireless` and `$.connection.type` fields as separate attributes when you create the index:\n\n[code example]\n\nAfter you create the new index, you can search for items with the wireless TAG set to `true`:\n\n[code example]\n\nYou can also search for items with a Bluetooth connection type:\n\n[code example]"
},
{
"id": "field-projection",
"title": "Field projection",
"role": "content",
"text": "[`FT.SEARCH`](https://redis.io/docs/latest/commands/ft.search) returns the entire JSON document by default. If you want to limit the returned search results to specific attributes, you can use field projection."
},
{
"id": "return-specific-attributes",
"title": "Return specific attributes",
"role": "returns",
"text": "When you run a search query, you can use the `RETURN` keyword to specify which attributes you want to include in the search results. You also need to specify the number of fields to return.\n\nFor example, this query only returns the `name` and `price` of each set of headphones:\n\n[code example]"
},
{
"id": "project-with-jsonpath",
"title": "Project with JSONPath",
"role": "content",
"text": "You can use [JSONPath](https://redis.io/docs/latest/develop/data-types/json/path) expressions in a `RETURN` statement to extract any part of the JSON document, even fields that were not defined in the index `SCHEMA`.\n\nFor example, the following query uses the JSONPath expression `$.stock` to return each item's stock in addition to the name and price attributes.\n\n[code example]\n\nNote that the returned property name is the JSONPath expression itself: `\"$.stock\"`.\n\nYou can use the `AS` option to specify an alias for the returned property:\n\n[code example]\n\nThis query returns the field as the alias `\"stock\"` instead of the JSONPath expression `\"$.stock\"`."
},
{
"id": "highlight-search-terms",
"title": "Highlight search terms",
"role": "content",
"text": "You can [highlight](https://redis.io/docs/latest/develop/ai/search-and-query/advanced-concepts/highlight) relevant search terms in any indexed `TEXT` attribute.\n\nFor JSON documents, you must use the `RETURN` parameter to specify the attributes, followed by `HIGHLIGHT` to indicate which of those attributes to highlight.\n\nUse the optional `TAGS` keyword to specify the strings that will surround (or highlight) the matching search terms.\n\n> [!NOTE]\n> `HIGHLIGHT` and `SUMMARIZE` are not supported when the JSONPath leads to multiple values (such as arrays indexed as `TEXT`). See [Index limitations](#index-limitations) for details.\n\nFor example, highlight the word \"bluetooth\" with bold HTML tags in item names and descriptions:\n\n[code example]"
},
{
"id": "aggregate-with-jsonpath",
"title": "Aggregate with JSONPath",
"role": "content",
"text": "You can use [aggregation](https://redis.io/docs/latest/develop/ai/search-and-query/advanced-concepts/aggregations) to generate statistics or build facet queries.\n\nThe `LOAD` option accepts [JSONPath](https://redis.io/docs/latest/develop/data-types/json/path) expressions. You can use any value in the pipeline, even if the value is not indexed.\n\nThis example uses aggregation to calculate a 10% price discount for each item and sorts the items from least expensive to most expensive:\n\n[code example]\n\n> [!NOTE]\n> [`FT.AGGREGATE`](https://redis.io/docs/latest/commands/ft.aggregate) queries require `attribute` modifiers. Don't use JSONPath expressions in queries, except with the `LOAD` option, because the query parser doesn't fully support them."
},
{
"id": "index-missing-or-empty-values",
"title": "Index missing or empty values",
"role": "content",
"text": "As of v2.10, you can search for missing properties, that is, properties that do not exist in a given document, using the `INDEXMISSING` option to `FT.CREATE` in conjunction with the `ismissing` query function with `FT.SEARCH`. You can also search for existing properties with no value (i.e., empty) using the `INDEXEMPTY` option with `FT.CREATE`. Both query types require DIALECT 2. Examples below:\n\n[code example]\n\n[code example]"
},
{
"id": "index-limitations",
"title": "Index limitations",
"role": "content",
"text": ""
},
{
"id": "schema-mapping",
"title": "Schema mapping",
"role": "content",
"text": "During index creation, you need to map the JSON elements to `SCHEMA` fields as follows:\n\n- Strings as `TEXT`, `TAG`, or `GEO`.\n- Numbers as `NUMERIC`.\n- Booleans as `TAG`.\n- JSON array\n - Array of strings as `TAG` or `TEXT`.\n - Array of numbers as `NUMERIC` or `VECTOR`.\n - Array of geo coordinates as `GEO`.\n - `null` values in such arrays are ignored.\n- You cannot index JSON objects. Index the individual elements as separate attributes instead.\n- `null` values are ignored."
},
{
"id": "jsonpath-with-multiple-values",
"title": "JSONPath with multiple values",
"role": "content",
"text": "When a JSONPath leads to an array or to multiple values:\n\n- No `HIGHLIGHT` and `SUMMARIZE` support.\n- `SORTBY` only sorts by the first value.\n- `RETURN` of a schema attribute returns the values as a JSON string.\n- If a JSONPath is specified by the `RETURN`, instead of a schema attribute, all values are returned (as a JSON string)."
}
],
"examples": [
{
"id": "create-index-with-json-schema-ex0",
"language": "sql",
"code": "FT.CREATE {index_name} ON JSON SCHEMA {json_path} AS {attribute} {type}",
"section_id": "create-index-with-json-schema"
},
{
"id": "create-index-with-json-schema-ex1",
"language": "sql",
"code": "127.0.0.1:6379> FT.CREATE itemIdx ON JSON PREFIX 1 item: SCHEMA $.name AS name TEXT $.description as description TEXT $.price AS price NUMERIC $.embedding AS embedding VECTOR FLAT 6 DIM 4 DISTANCE_METRIC L2 TYPE FLOAT32",
"section_id": "create-index-with-json-schema"
},
{
"id": "add-json-documents-ex0",
"language": "json",
"code": "{\n \"name\": \"Noise-cancelling Bluetooth headphones\",\n \"description\": \"Wireless Bluetooth headphones with noise-cancelling technology\",\n \"connection\": {\n \"wireless\": true,\n \"type\": \"Bluetooth\"\n },\n \"price\": 99.98,\n \"stock\": 25,\n \"colors\": [\n \"black\",\n \"silver\"\n ],\n \"embedding\": [0.87, -0.15, 0.55, 0.03]\n}",
"section_id": "add-json-documents"
},
{
"id": "add-json-documents-ex1",
"language": "json",
"code": "{\n \"name\": \"Wireless earbuds\",\n \"description\": \"Wireless Bluetooth in-ear headphones\",\n \"connection\": {\n \"wireless\": true,\n \"type\": \"Bluetooth\"\n },\n \"price\": 64.99,\n \"stock\": 17,\n \"colors\": [\n \"black\",\n \"white\"\n ],\n \"embedding\": [-0.7, -0.51, 0.88, 0.14]\n}",
"section_id": "add-json-documents"
},
{
"id": "add-json-documents-ex2",
"language": "sql",
"code": "127.0.0.1:6379> JSON.SET item:1 $ '{\"name\":\"Noise-cancelling Bluetooth headphones\",\"description\":\"Wireless Bluetooth headphones with noise-cancelling technology\",\"connection\":{\"wireless\":true,\"type\":\"Bluetooth\"},\"price\":99.98,\"stock\":25,\"colors\":[\"black\",\"silver\"],\"embedding\":[0.87,-0.15,0.55,0.03]}'\n\"OK\"\n127.0.0.1:6379> JSON.SET item:2 $ '{\"name\":\"Wireless earbuds\",\"description\":\"Wireless Bluetooth in-ear headphones\",\"connection\":{\"wireless\":true,\"type\":\"Bluetooth\"},\"price\":64.99,\"stock\":17,\"colors\":[\"black\",\"white\"],\"embedding\":[-0.7,-0.51,0.88,0.14]}'\n\"OK\"",
"section_id": "add-json-documents"
},
{
"id": "search-the-index-ex0",
"language": "sql",
"code": "127.0.0.1:6379> FT.SEARCH itemIdx '@name:(earbuds)'\n1) \"1\"\n2) \"item:2\"\n3) 1) \"$\"\n 2) \"{\\\"name\\\":\\\"Wireless earbuds\\\",\\\"description\\\":\\\"Wireless Bluetooth in-ear headphones\\\",\\\"connection\\\":{\\\"wireless\\\":true,\\\"connection\\\":\\\"Bluetooth\\\"},\\\"price\\\":64.99,\\\"stock\\\":17,\\\"colors\\\":[\\\"black\\\",\\\"white\\\"],\\\"embedding\\\":[-0.7,-0.51,0.88,0.14]}\"",
"section_id": "search-the-index"
},
{
"id": "search-the-index-ex1",
"language": "sql",
"code": "127.0.0.1:6379> FT.SEARCH itemIdx '@description:(bluetooth headphones)'\n1) \"2\"\n2) \"item:1\"\n3) 1) \"$\"\n 2) \"{\\\"name\\\":\\\"Noise-cancelling Bluetooth headphones\\\",\\\"description\\\":\\\"Wireless Bluetooth headphones with noise-cancelling technology\\\",\\\"connection\\\":{\\\"wireless\\\":true,\\\"type\\\":\\\"Bluetooth\\\"},\\\"price\\\":99.98,\\\"stock\\\":25,\\\"colors\\\":[\\\"black\\\",\\\"silver\\\"], \\\"embedding\\\":[0.87,-0.15,0.55,0.03]}\"\n4) \"item:2\"\n5) 1) \"$\"\n 2) \"{\\\"name\\\":\\\"Wireless earbuds\\\",\\\"description\\\":\\\"Wireless Bluetooth in-ear headphones\\\",\\\"connection\\\":{\\\"wireless\\\":true,\\\"connection\\\":\\\"Bluetooth\\\"},\\\"price\\\":64.99,\\\"stock\\\":17,\\\"colors\\\":[\\\"black\\\",\\\"white\\\"],\\\"embedding\\\":[-0.7,-0.51,0.88,0.14]}\"",
"section_id": "search-the-index"
},
{
"id": "search-the-index-ex2",
"language": "sql",
"code": "127.0.0.1:6379> FT.SEARCH itemIdx '@description:(bluetooth headphones) @price:[0 70]'\n1) \"1\"\n2) \"item:2\"\n3) 1) \"$\"\n 2) \"{\\\"name\\\":\\\"Wireless earbuds\\\",\\\"description\\\":\\\"Wireless Bluetooth in-ear headphones\\\",\\\"connection\\\":{\\\"wireless\\\":true,\\\"connection\\\":\\\"Bluetooth\\\"},\\\"price\\\":64.99,\\\"stock\\\":17,\\\"colors\\\":[\\\"black\\\",\\\"white\\\"],\\\"embedding\\\":[-0.7,-0.51,0.88,0.14]}\"",
"section_id": "search-the-index"
},
{
"id": "search-the-index-ex3",
"language": "sql",
"code": "127.0.0.1:6379> FT.SEARCH itemIdx '@description:(bluetooth headphones)=>[KNN 2 @embedding $blob]' PARAMS 2 blob \\x01\\x01\\x01\\x01 DIALECT 2\n1) \"2\"\n2) \"item:1\"\n3) 1) \"__embedding_score\"\n 2) \"1.08280003071\"\n 1) \"$\"\n 2) \"{\\\"name\\\":\\\"Noise-cancelling Bluetooth headphones\\\",\\\"description\\\":\\\"Wireless Bluetooth headphones with noise-cancelling technology\\\",\\\"connection\\\":{\\\"wireless\\\":true,\\\"type\\\":\\\"Bluetooth\\\"},\\\"price\\\":99.98,\\\"stock\\\":25,\\\"colors\\\":[\\\"black\\\",\\\"silver\\\"],\\\"embedding\\\":[0.87,-0.15,0.55,0.03]}\"\n2) \"item:2\"\n3) 1) \"__embedding_score\"\n 2) \"1.54409992695\"\n 3) \"$\"\n 4) \"{\\\"name\\\":\\\"Wireless earbuds\\\",\\\"description\\\":\\\"Wireless Bluetooth in-ear headphones\\\",\\\"connection\\\":{\\\"wireless\\\":true,\\\"connection\\\":\\\"Bluetooth\\\"},\\\"price\\\":64.99,\\\"stock\\\":17,\\\"colors\\\":[\\\"black\\\",\\\"white\\\"],\\\"embedding\\\":[-0.7,-0.51,0.88,0.14]}\"",
"section_id": "search-the-index"
},
{
"id": "hash-documents-ex0",
"language": "sql",
"code": "# HASH: Comma is the default separator\nHSET product:1 category \"Electronics,Gaming,PC\"\nFT.CREATE products ON HASH PREFIX 1 product: SCHEMA category TAG\n\n# Result: Creates 3 separate tags: \"Electronics\", \"Gaming\", \"PC\"\nFT.SEARCH products '@category:{Gaming}' # ✅ Finds the document",
"section_id": "hash-documents"
},
{
"id": "json-documents-ex0",
"language": "sql",
"code": "# JSON: No default separator - the entire string becomes one tag\nJSON.SET product:1 $ '{\"category\": \"Electronics,Gaming,PC\"}'\nFT.CREATE products ON JSON PREFIX 1 product: SCHEMA $.category AS category TAG\n\n# Result: Creates 1 tag: \"Electronics,Gaming,PC\"\nFT.SEARCH products '@category:{Gaming}' # ❌ Does NOT find the document\nFT.SEARCH products '@category:{Electronics,Gaming,PC}' # ✅ Finds the document",
"section_id": "json-documents"
},
{
"id": "making-json-documents-behave-like-hash-documents-ex0",
"language": "sql",
"code": "JSON.SET product:1 $ '{\"category\": \"Electronics,Gaming,PC\"}'\nFT.CREATE products ON JSON PREFIX 1 product: SCHEMA $.category AS category TAG SEPARATOR \",\"\n\n# Result: Creates 3 separate tags: \"Electronics\", \"Gaming\", \"PC\"\nFT.SEARCH products '@category:{Gaming}' # ✅ Now finds the document",
"section_id": "making-json-documents-behave-like-hash-documents"
},
{
"id": "recommended-approach-for-json-ex0",
"language": "sql",
"code": "JSON.SET product:1 $ '{\"category\": [\"Electronics\", \"Gaming\", \"PC\"]}'\nFT.CREATE products ON JSON PREFIX 1 product: SCHEMA $.category[*] AS category TAG\n\n# Result: Creates 3 separate tags: \"Electronics\", \"Gaming\", \"PC\"\nFT.SEARCH products '@category:{Gaming}' # ✅ Finds the document",
"section_id": "recommended-approach-for-json"
},
{
"id": "approach-1-json-arrays-recommended-ex0",
"language": "sql",
"code": "# Create index with array indexing\n127.0.0.1:6379> FT.CREATE itemIdx2 ON JSON PREFIX 1 item: SCHEMA $.colors[*] AS colors TAG $.name AS name TEXT $.description as description TEXT\n\n# The JSON data uses arrays\n# Each array element (\"black\", \"silver\") becomes a separate tag",
"section_id": "approach-1-json-arrays-recommended"
},
{
"id": "approach-1-json-arrays-recommended-ex1",
"language": "sql",
"code": "127.0.0.1:6379> FT.SEARCH itemIdx2 \"@colors:{silver} (@name:(headphones)|@description:(headphones))\"\n1) \"1\"\n2) \"item:1\"\n3) 1) \"$\"\n 2) \"{\\\"name\\\":\\\"Noise-cancelling Bluetooth headphones\\\",\\\"description\\\":\\\"Wireless Bluetooth headphones with noise-cancelling technology\\\",\\\"connection\\\":{\\\"wireless\\\":true,\\\"type\\\":\\\"Bluetooth\\\"},\\\"price\\\":99.98,\\\"stock\\\":25,\\\"colors\\\":[\\\"black\\\",\\\"silver\\\"]}\"",
"section_id": "approach-1-json-arrays-recommended"
},
{
"id": "approach-2-strings-with-explicit-separators-ex0",
"language": "sql",
"code": "# JSON with comma-separated string\nJSON.SET item:1 $ '{\"colors\": \"black,silver,gold\"}'\n\n# Index with explicit separator\nFT.CREATE itemIdx3 ON JSON PREFIX 1 item: SCHEMA $.colors AS colors TAG SEPARATOR \",\"\n\n# Now you can search individual colors\nFT.SEARCH itemIdx3 \"@colors:{silver}\"",
"section_id": "approach-2-strings-with-explicit-separators"
},
{
"id": "index-json-arrays-as-text-ex0",
"language": "sql",
"code": "127.0.0.1:6379> FT.CREATE itemIdx3 ON JSON PREFIX 1 item: SCHEMA $.colors AS colors TEXT $.name AS name TEXT $.description as description TEXT",
"section_id": "index-json-arrays-as-text"
},
{
"id": "index-json-arrays-as-text-ex1",
"language": "sql",
"code": "127.0.0.1:6379> JSON.SET item:3 $ '{\"name\":\"True Wireless earbuds\",\"description\":\"True Wireless Bluetooth in-ear headphones\",\"connection\":{\"wireless\":true,\"type\":\"Bluetooth\"},\"price\":74.99,\"stock\":20,\"colors\":[\"red\",\"light blue\"]}'\n\"OK\"",
"section_id": "index-json-arrays-as-text"
},
{
"id": "index-json-arrays-as-text-ex2",
"language": "sql",
"code": "127.0.0.1:6379> FT.SEARCH itemIdx3 '@colors:(white|light) (@name|description:(headphones))' RETURN 1 $.colors\n1) (integer) 2\n2) \"item:2\"\n3) 1) \"$.colors\"\n 2) \"[\\\"black\\\",\\\"white\\\"]\"\n4) \"item:3\"\n5) 1) \"$.colors\"\n 2) \"[\\\"red\\\",\\\"light blue\\\"]\"",
"section_id": "index-json-arrays-as-text"
},
{
"id": "limitations-ex0",
"language": "json",
"code": "{\n \"a\": [\n {\"b\": [\"first first\", \"first second\"]},\n {\"c\":\n {\"b\": [\"second first\", \"second second\"]}},\n {\"b\": [\"third first\", \"third second\"]}\n ]\n }",
"section_id": "limitations"
},
{
"id": "index-json-arrays-as-numeric-ex0",
"language": "sql",
"code": "127.0.0.1:6379> JSON.SET item:1 $ '{\"name\":\"Noise-cancelling Bluetooth headphones\",\"description\":\"Wireless Bluetooth headphones with noise-cancelling technology\",\"connection\":{\"wireless\":true,\"type\":\"Bluetooth\"},\"price\":99.98,\"stock\":25,\"colors\":[\"black\",\"silver\"], \"max_level\":[60, 70, 80, 90, 100]}'\nOK\n\n127.0.0.1:6379> JSON.SET item:2 $ '{\"name\":\"Wireless earbuds\",\"description\":\"Wireless Bluetooth in-ear headphones\",\"connection\":{\"wireless\":true,\"type\":\"Bluetooth\"},\"price\":64.99,\"stock\":17,\"colors\":[\"black\",\"white\"], \"max_level\":[80, 100, 120]}'\nOK\n\n127.0.0.1:6379> JSON.SET item:3 $ '{\"name\":\"True Wireless earbuds\",\"description\":\"True Wireless Bluetooth in-ear headphones\",\"connection\":{\"wireless\":true,\"type\":\"Bluetooth\"},\"price\":74.99,\"stock\":20,\"colors\":[\"red\",\"light blue\"], \"max_level\":[90, 100, 110, 120]}'\nOK",
"section_id": "index-json-arrays-as-numeric"
},
{
"id": "index-json-arrays-as-numeric-ex1",
"language": "sql",
"code": "127.0.0.1:6379> FT.CREATE itemIdx4 ON JSON PREFIX 1 item: SCHEMA $.max_level AS dB NUMERIC\nOK",
"section_id": "index-json-arrays-as-numeric"
},
{
"id": "index-json-arrays-as-numeric-ex2",
"language": "sql",
"code": "127.0.0.1:6379> FT.SEARCH itemIdx4 '@dB:[70 80]'\n1) (integer) 2\n2) \"item:1\"\n3) 1) \"$\"\n 2) \"{\\\"name\\\":\\\"Noise-cancelling Bluetooth headphones\\\",\\\"description\\\":\\\"Wireless Bluetooth headphones with noise-cancelling technology\\\",\\\"connection\\\":{\\\"wireless\\\":true,\\\"type\\\":\\\"Bluetooth\\\"},\\\"price\\\":99.98,\\\"stock\\\":25,\\\"colors\\\":[\\\"black\\\",\\\"silver\\\"],\\\"max_level\\\":[60,70,80,90,100]}\"\n4) \"item:2\"\n5) 1) \"$\"\n 2) \"{\\\"name\\\":\\\"Wireless earbuds\\\",\\\"description\\\":\\\"Wireless Bluetooth in-ear headphones\\\",\\\"connection\\\":{\\\"wireless\\\":true,\\\"type\\\":\\\"Bluetooth\\\"},\\\"price\\\":64.99,\\\"stock\\\":17,\\\"colors\\\":[\\\"black\\\",\\\"white\\\"],\\\"max_level\\\":[80,100,120]}\"",
"section_id": "index-json-arrays-as-numeric"
},
{
"id": "index-json-arrays-as-numeric-ex3",
"language": "sql",
"code": "127.0.0.1:6379> FT.SEARCH itemIdx4 '-@dB:[-inf (90] -@dB:[(120 +inf]'\n1) (integer) 1\n2) \"item:3\"\n3) 1) \"$\"\n 2) \"{\\\"name\\\":\\\"True Wireless earbuds\\\",\\\"description\\\":\\\"True Wireless Bluetooth in-ear headphones\\\",\\\"connection\\\":{\\\"wireless\\\":true,\\\"type\\\":\\\"Bluetooth\\\"},\\\"price\\\":74.99,\\\"stock\\\":20,\\\"colors\\\":[\\\"red\\\",\\\"light blue\\\"],\\\"max_level\\\":[90,100,110,120]}\"",
"section_id": "index-json-arrays-as-numeric"
},
{
"id": "index-json-arrays-as-vector-ex0",
"language": "sql",
"code": "127.0.0.1:6379> FT.CREATE itemIdx5 ON JSON PREFIX 1 item: SCHEMA $.embedding AS embedding VECTOR FLAT 6 DIM 4 DISTANCE_METRIC L2 TYPE FLOAT32\nOK\n127.0.0.1:6379> JSON.SET item:1 $ '{\"name\":\"Noise-cancelling Bluetooth headphones\",\"description\":\"Wireless Bluetooth headphones with noise-cancelling technology\",\"price\":99.98,\"stock\":25,\"colors\":[\"black\",\"silver\"],\"embedding\":[0.87,-0.15,0.55,0.03]}'\nOK\n127.0.0.1:6379> JSON.SET item:2 $ '{\"name\":\"Wireless earbuds\",\"description\":\"Wireless Bluetooth in-ear headphones\",\"price\":64.99,\"stock\":17,\"colors\":[\"black\",\"white\"],\"embedding\":[-0.7,-0.51,0.88,0.14]}'\nOK",
"section_id": "index-json-arrays-as-vector"
},
{
"id": "index-json-arrays-as-vector-ex1",
"language": "sql",
"code": "127.0.0.1:6379> FT.SEARCH itemIdx5 '*=>[KNN 2 @embedding $blob AS dist]' SORTBY dist PARAMS 2 blob \\x01\\x01\\x01\\x01 DIALECT 2\n1) (integer) 2\n2) \"item:1\"\n3) 1) \"dist\"\n 2) \"1.08280003071\"\n 3) \"$\"\n 4) \"{\\\"name\\\":\\\"Noise-cancelling Bluetooth headphones\\\",\\\"description\\\":\\\"Wireless Bluetooth headphones with noise-cancelling technology\\\",\\\"price\\\":99.98,\\\"stock\\\":25,\\\"colors\\\":[\\\"black\\\",\\\"silver\\\"],\\\"embedding\\\":[0.87,-0.15,0.55,0.03]}\"\n4) \"item:2\"\n5) 1) \"dist\"\n 2) \"1.54409992695\"\n 3) \"$\"\n 4) \"{\\\"name\\\":\\\"Wireless earbuds\\\",\\\"description\\\":\\\"Wireless Bluetooth in-ear headphones\\\",\\\"price\\\":64.99,\\\"stock\\\":17,\\\"colors\\\":[\\\"black\\\",\\\"white\\\"],\\\"embedding\\\":[-0.7,-0.51,0.88,0.14]}\"",
"section_id": "index-json-arrays-as-vector"
},
{
"id": "index-json-arrays-as-vector-ex2",
"language": "sql",
"code": "127.0.0.1:6379> FT.CREATE itemIdx5 ON JSON PREFIX 1 item: SCHEMA $.embeddings[*] AS embeddings VECTOR FLAT 6 DIM 4 DISTANCE_METRIC L2 TYPE FLOAT32\nOK\n127.0.0.1:6379> JSON.SET item:1 $ '{\"name\":\"Noise-cancelling Bluetooth headphones\",\"description\":\"Wireless Bluetooth headphones with noise-cancelling technology\",\"price\":99.98,\"stock\":25,\"colors\":[\"black\",\"silver\"],\"embeddings\":[[0.87,-0.15,0.55,0.03]]}'\nOK\n127.0.0.1:6379> JSON.SET item:2 $ '{\"name\":\"Wireless earbuds\",\"description\":\"Wireless Bluetooth in-ear headphones\",\"price\":64.99,\"stock\":17,\"colors\":[\"black\",\"white\"],\"embeddings\":[[-0.7,-0.51,0.88,0.14],[-0.8,-0.15,0.33,-0.01]]}'\nOK",
"section_id": "index-json-arrays-as-vector"
},
{
"id": "index-json-arrays-as-vector-ex3",
"language": "sql",
"code": "127.0.0.1:6379> FT.SEARCH itemIdx5 '*=>[KNN 2 @embeddings $blob AS dist]' SORTBY dist PARAMS 2 blob \\x01\\x01\\x01\\x01 DIALECT 2\n1) (integer) 2\n2) \"item:2\"\n3) 1) \"dist\"\n 2) \"0.771500051022\"\n 3) \"$\"\n 4) \"{\\\"name\\\":\\\"Wireless earbuds\\\",\\\"description\\\":\\\"Wireless Bluetooth in-ear headphones\\\",\\\"price\\\":64.99,\\\"stock\\\":17,\\\"colors\\\":[\\\"black\\\",\\\"white\\\"],\\\"embeddings\\\":[[-0.7,-0.51,0.88,0.14],[-0.8,-0.15,0.33,-0.01]]}\"\n4) \"item:1\"\n5) 1) \"dist\"\n 2) \"1.08280003071\"\n 3) \"$\"\n 4) \"{\\\"name\\\":\\\"Noise-cancelling Bluetooth headphones\\\",\\\"description\\\":\\\"Wireless Bluetooth headphones with noise-cancelling technology\\\",\\\"price\\\":99.98,\\\"stock\\\":25,\\\"colors\\\":[\\\"black\\\",\\\"silver\\\"],\\\"embeddings\\\":[[0.87,-0.15,0.55,0.03]]}\"",
"section_id": "index-json-arrays-as-vector"
},
{
"id": "index-json-objects-ex0",
"language": "sql",
"code": "127.0.0.1:6379> FT.CREATE itemIdx3 ON JSON SCHEMA $.connection.wireless AS wireless TAG $.connection.type AS connectionType TEXT\n\"OK\"",
"section_id": "index-json-objects"
},
{
"id": "index-json-objects-ex1",
"language": "sql",
"code": "127.0.0.1:6379> FT.SEARCH itemIdx3 '@wireless:{true}'\n1) \"2\"\n2) \"item:2\"\n3) 1) \"$\"\n 2) \"{\\\"name\\\":\\\"Wireless earbuds\\\",\\\"description\\\":\\\"Wireless Bluetooth in-ear headphones\\\",\\\"connection\\\":{\\\"wireless\\\":true,\\\"connection\\\":\\\"Bluetooth\\\"},\\\"price\\\":64.99,\\\"stock\\\":17,\\\"colors\\\":[\\\"black\\\",\\\"white\\\"]}\"\n4) \"item:1\"\n5) 1) \"$\"\n 2) \"{\\\"name\\\":\\\"Noise-cancelling Bluetooth headphones\\\",\\\"description\\\":\\\"Wireless Bluetooth headphones with noise-cancelling technology\\\",\\\"connection\\\":{\\\"wireless\\\":true,\\\"type\\\":\\\"Bluetooth\\\"},\\\"price\\\":99.98,\\\"stock\\\":25,\\\"colors\\\":[\\\"black\\\",\\\"silver\\\"]}\"",
"section_id": "index-json-objects"
},
{
"id": "index-json-objects-ex2",
"language": "sql",
"code": "127.0.0.1:6379> FT.SEARCH itemIdx3 '@connectionType:(bluetooth)'\n1) \"2\"\n2) \"item:1\"\n3) 1) \"$\"\n 2) \"{\\\"name\\\":\\\"Noise-cancelling Bluetooth headphones\\\",\\\"description\\\":\\\"Wireless Bluetooth headphones with noise-cancelling technology\\\",\\\"connection\\\":{\\\"wireless\\\":true,\\\"type\\\":\\\"Bluetooth\\\"},\\\"price\\\":99.98,\\\"stock\\\":25,\\\"colors\\\":[\\\"black\\\",\\\"silver\\\"]}\"\n4) \"item:2\"\n5) 1) \"$\"\n 2) \"{\\\"name\\\":\\\"Wireless earbuds\\\",\\\"description\\\":\\\"Wireless Bluetooth in-ear headphones\\\",\\\"connection\\\":{\\\"wireless\\\":true,\\\"type\\\":\\\"Bluetooth\\\"},\\\"price\\\":64.99,\\\"stock\\\":17,\\\"colors\\\":[\\\"black\\\",\\\"white\\\"]}\"",
"section_id": "index-json-objects"
},
{
"id": "return-specific-attributes-ex0",
"language": "sql",
"code": "127.0.0.1:6379> FT.SEARCH itemIdx '@description:(headphones)' RETURN 2 name price\n1) \"2\"\n2) \"item:1\"\n3) 1) \"name\"\n 2) \"Noise-cancelling Bluetooth headphones\"\n 3) \"price\"\n 4) \"99.98\"\n4) \"item:2\"\n5) 1) \"name\"\n 2) \"Wireless earbuds\"\n 3) \"price\"\n 4) \"64.99\"",
"section_id": "return-specific-attributes"
},
{
"id": "project-with-jsonpath-ex0",
"language": "sql",
"code": "127.0.0.1:6379> FT.SEARCH itemIdx '@description:(headphones)' RETURN 3 name price $.stock\n1) \"2\"\n2) \"item:1\"\n3) 1) \"name\"\n 2) \"Noise-cancelling Bluetooth headphones\"\n 3) \"price\"\n 4) \"99.98\"\n 5) \"$.stock\"\n 6) \"25\"\n4) \"item:2\"\n5) 1) \"name\"\n 2) \"Wireless earbuds\"\n 3) \"price\"\n 4) \"64.99\"\n 5) \"$.stock\"\n 6) \"17\"",
"section_id": "project-with-jsonpath"
},
{
"id": "project-with-jsonpath-ex1",
"language": "sql",
"code": "127.0.0.1:6379> FT.SEARCH itemIdx '@description:(headphones)' RETURN 5 name price $.stock AS stock\n1) \"2\"\n2) \"item:1\"\n3) 1) \"name\"\n 2) \"Noise-cancelling Bluetooth headphones\"\n 3) \"price\"\n 4) \"99.98\"\n 5) \"stock\"\n 6) \"25\"\n4) \"item:2\"\n5) 1) \"name\"\n 2) \"Wireless earbuds\"\n 3) \"price\"\n 4) \"64.99\"\n 5) \"stock\"\n 6) \"17\"",
"section_id": "project-with-jsonpath"
},
{
"id": "highlight-search-terms-ex0",
"language": "sql",
"code": "127.0.0.1:6379> FT.SEARCH itemIdx '(@name:(bluetooth))|(@description:(bluetooth))' RETURN 3 name description price HIGHLIGHT FIELDS 2 name description TAGS '' ''\n1) \"2\"\n2) \"item:1\"\n3) 1) \"name\"\n 2) \"Noise-cancelling Bluetooth headphones\"\n 3) \"description\"\n 4) \"Wireless Bluetooth headphones with noise-cancelling technology\"\n 5) \"price\"\n 6) \"99.98\"\n4) \"item:2\"\n5) 1) \"name\"\n 2) \"Wireless earbuds\"\n 3) \"description\"\n 4) \"Wireless Bluetooth in-ear headphones\"\n 5) \"price\"\n 6) \"64.99\"",
"section_id": "highlight-search-terms"
},
{
"id": "aggregate-with-jsonpath-ex0",
"language": "sql",
"code": "127.0.0.1:6379> FT.AGGREGATE itemIdx '*' LOAD 4 name $.price AS originalPrice APPLY '@originalPrice - (@originalPrice * 0.10)' AS salePrice SORTBY 2 @salePrice ASC\n1) \"2\"\n2) 1) \"name\"\n 2) \"Wireless earbuds\"\n 3) \"originalPrice\"\n 4) \"64.99\"\n 5) \"salePrice\"\n 6) \"58.491\"\n3) 1) \"name\"\n 2) \"Noise-cancelling Bluetooth headphones\"\n 3) \"originalPrice\"\n 4) \"99.98\"\n 5) \"salePrice\"\n 6) \"89.982\"",
"section_id": "aggregate-with-jsonpath"
},
{
"id": "index-missing-or-empty-values-ex0",
"language": "plaintext",
"code": "JSON.SET key:1 $ '{\"propA\": \"foo\"}'\nJSON.SET key:2 $ '{\"propA\": \"bar\", \"propB\":\"abc\"}'\nFT.CREATE idx ON JSON PREFIX 1 key: SCHEMA $.propA AS propA TAG $.propB AS propB TAG INDEXMISSING\n\n> FT.SEARCH idx 'ismissing(@propB)' DIALECT 2\n1) \"1\"\n2) \"key:1\"\n3) 1) \"$\"\n 2) \"{\\\"propA\\\":\\\"foo\\\"}\"",
"section_id": "index-missing-or-empty-values"
},
{
"id": "index-missing-or-empty-values-ex1",
"language": "plaintext",
"code": "JSON.SET key:1 $ '{\"propA\": \"foo\", \"propB\":\"\"}'\nJSON.SET key:2 $ '{\"propA\": \"bar\", \"propB\":\"abc\"}'\nFT.CREATE idx ON JSON PREFIX 1 key: SCHEMA $.propA AS propA TAG $.propB AS propB TAG INDEXEMPTY\n\n> FT.SEARCH idx '@propB:{\"\"}' DIALECT 2\n1) \"1\"\n2) \"key:1\"\n3) 1) \"$\"\n 2) \"{\\\"propA\\\":\\\"foo\\\",\\\"propB\\\":\\\"\\\"}\"",
"section_id": "index-missing-or-empty-values"
}
]
}