FT.CREATE

The FT.CREATE command creates an empty index and may initiate the backfill process. Each index consists of a number of field definitions. Each field definition specifies a field name, a field type and a path within each indexed key to locate a value of the declared type. Some field type definitions have additional sub-type specifiers.

For indexes on HASH keys, the default path is the same as the hash member name. The optional AS clause can be used to rename the field if desired

For indexes on JSON keys, the path is a JSON path to the data of the declared type. The AS clause is required in order to provide a field name without the special characters of a JSON path.

FT.CREATE <index-name>
    [ON HASH | ON JSON]
    [PREFIX <count> <prefix> [<prefix>...]]
    [FILTER <expression>]
    [SCORE default_value]
    [SCORE_FIELD <field_name>]
    [LANGUAGE <language>]
    [SKIPINITIALSCAN]
    [MINSTEMSIZE <min_stem_size>]
    [WITHOFFSETS | NOOFFSETS]
    [NOHL]
    [NOSTOPWORDS | STOPWORDS <count> <word> word ...]
    [PUNCTUATION <punctuation>]
    SCHEMA
        (
            <field-identifier> [AS <field-alias>]
                  NUMERIC
                | TAG [SEPARATOR <sep>] [CASESENSITIVE]
                | TEXT [NOSTEM] [WITHSUFFIXTRIE | NOSUFFIXTRIE] [WEIGHT <weight>]
                | VECTOR [HNSW | FLAT] <attr_count> [<attribute_name> <attribute_value>]+
            [SORTABLE [UNF]]
        )+

• <index-name> (required): This is the name you give to your index. If an index with the same name exists already, an error is returned.

• ON HASH | ON JSON (optional): Only keys that match the specified type are included into this index. If omitted, HASH is assumed.

• PREFIX <prefix-count> <prefix> (optional): If this clause is specified, then only keys that begin with the same bytes as one or more of the specified prefixes will be included into this index. If this clause is omitted, all keys of the correct type will be included. A zero-length prefix would also match all keys of the correct type.

• FILTER <expression> (optional): A boolean expression evaluated for each candidate key during ingestion; only keys for which it evaluates to true are included in the index. A comparison involving a missing field is false, so a key that has no status field is admitted by neither @status == 'active' nor @status != 'active' — a negation such as !(@status == 'active') admits it instead, because the comparison it negates is false. The number of keys excluded by the filter is reported by FT.INFO as filter_rejected_keys.

  See Search - expressions for details on the expression syntax.

  A field's value always reaches the expression as its stored bytes, whatever type the SCHEMA declares — a NUMERIC field is not a number to a FILTER. A comparison is numeric only when one side really is a number, meaning a bare numeric literal such as 5 or a number-returning function such as strlen(). So @price > 100 compares numerically, while @price > '100' and @price > @cost compare the values as strings, byte by byte. In a numeric comparison a value that is not a number is unordered: @price != 5 is true for it and every other comparison is false.

  Field references use the @<name> syntax. For a HASH index the expression may reference a field that is not declared in the SCHEMA; its value is read directly off the key at ingestion time (an absent field makes the comparison false). Because an undeclared field name is read verbatim from the key, a misspelled field name does not produce an error — watch filter_rejected_keys in FT.INFO to detect this. For a JSON index every field referenced by the expression must be declared in the SCHEMA; referencing an undeclared field is rejected when the index is created.

• LANGUAGE <language> (optional): For text fields, the language used to control lexical parsing and stemming. It selects the stemmer and the default punctuation and stop words. Supported values: ENGLISH (default), ARABIC, DUTCH, FRENCH, GERMAN, INDONESIAN, ITALIAN, PORTUGUESE, RUSSIAN, SPANISH, SWEDISH, TURKISH. Languages other than English require 1.3.0 or later.

• MINSTEMSIZE <min_stem_size> (optional): For text fields with stemming enabled. This controls the minimum length of a word, in characters (Unicode code points), required for it to be subjected to stemming. The default value is 4. On English indexes with search.emulate-release below 1.3.0, the length is counted in bytes (see COMPATIBILITY.md).

• WITHOFFSETS | NOOFFSETS (optional): Enables/Disables the retention of per-word offsets within a text field. Offsets are required to perform exact phrase matching and slop-based proximity matching. Thus if offsets are disabled, those query operations will be rejected with an error. The default is WITHOFFSETS.

• NOHL (optional): This parameter is accepted for compatibility, but has no effect.

• NOSTOPWORDS | STOPWORDS <count> <word1> <word2>... (optional): Stop words are words which are not put into the indexes. The default value of STOPWORDSis language dependent. ForLANGUAGE ENGLISH the default is: [a, an, and, are, as, at, be, but, by, for, if, in, into, is, it, no, not, of, on, or, such, that, their, then, there, these, they, this, to, was, will, with].

• PUNCTUATION <punctuation> (optional): A string of characters that define the separation points between words, in addition to whitespace characters (spaces, tabs, newlines, carriage returns, and control characters) which always break words. Each character, including a multi-byte one such as —, is matched as a whole Unicode code point; before 1.3 each byte of a multi-byte character was matched separately, which also split unrelated characters sharing those bytes. The default value depends on LANGUAGE; for English it is ,.<>{}[]"':;!@#$%^&\*()-+=~/\|?.

• SKIPINITIALSCAN (optional): If specified, this option skips the normal backfill operation for an index. If this option is specified, pre-existing keys which match the PREFIX clause will not be loaded into the index during a backfill operation. This clause has no effect on processing of key mutations after an index is created, i.e., keys which are mutated after an index is created and satisfy the data type and PREFIX clause will be inserted into that index.

• SCORE (optional): Sets the default document score used for text search ranking. The value must be between 0.0 and 1.0. When SCORE_FIELD is configured, this value is used as the fallback if a document's score field is missing or cannot be parsed. (default: 1.0)

• SCORE_FIELD <field_name> (optional): Specifies the name of a hash field whose numeric value is used as the per-document score. When configured, the value of this field is read during ingestion and stored as the document's relevance score for text search ranking. If the field is missing or cannot be parsed as a valid number, the index-level SCORE default is used. The raw value is stored without clamping; the scoring algorithm determines how to handle values at query time.

Field types

TAG: A tag field is a string that contains one or more tag values.

• SEPARATOR <sep> (optional): One of these characters ,.<>{}[]"':;!@#$%^&*()-+=~ used to delimit individual tags. If omitted the default value is ,.
• CASESENSITIVE (optional): If present, tag comparisons will be case sensitive. The default is that tag comparisons are NOT case sensitive.

See Tag Field Format for more details and examples.

TEXT: A text field is a string that contains words

• NOSTEM (optional): If specified, stemming of words on ingestion is disabled.
• WITHSUFFIXTRIE | NOSUFFIXTRIE (optional): Enables/Disables the use of a suffix trie to implement suffix-based wildcard queries. If NOSUFFIXTRIE is specified, query strings which specify suffix-based wildcard matching will be rejected with an error. The default is WITHSUFFIXTRIE.
• WEIGHT <weight> (optional): The current implementation only allows the value to be 1.0. This parameter is accepted to make valkey-search more interoperable with RediSearch. (default: 1.0)

See Text Field Format for more details and examples.

NUMERIC: A numeric field contains a number.

See Numeric Field Format for details and examples.

VECTOR: A vector field contains a vector. Two vector indexing algorithms are currently supported: HNSW (Hierarchical Navigable Small World) and FLAT (brute force). Each algorithm has a set of additional attributes, some required and other optional.

• FLAT: This algorithm provides exact answers, but has runtime proportional to the number of indexed vectors and thus may not be appropriate for large data sets.
  • DIM <number> (required): Specifies the number of dimensions in a vector.
  • TYPE [FLOAT32 | FLOAT16 | BFLOAT16] (required): Element data type. FLOAT16 and BFLOAT16 halve the memory used per vector at some cost in precision; see Supported Data Types.
  • DISTANCE_METRIC [L2 | IP | COSINE] (required): Specifies the distance algorithm
  • INITIAL_CAP <size> (optional): Initial index size.
• HNSW: The HNSW algorithm provides approximate answers, but operates substantially faster than FLAT.
  • DIM <number> (required): Specifies the number of dimensions in a vector.
  • TYPE [FLOAT32 | FLOAT16 | BFLOAT16] (required): Element data type. FLOAT16 and BFLOAT16 halve the memory used per vector at some cost in precision; see Supported Data Types.
  • INITIAL_CAP <size> (optional): Initial index size.
  • M <number> (optional): Number of maximum allowed outgoing edges for each node in the graph in each layer. on layer zero the maximal number of outgoing edges will be 2*M. Default is 16, the maximum is 512.
  • EF_CONSTRUCTION <number> (optional): controls the number of vectors examined during index construction. Higher values for this parameter will improve recall ratio at the expense of longer index creation times. The default value is 200. Maximum value is 4096.
  • EF_RUNTIME <number> (optional): controls the number of vectors to be examined during a query operation. The default is 10, and the max is 4096. You can set this parameter value for each query you run. Higher values increase query times, but improve query recall.
  • DISTANCE_METRIC [L2 | IP | COSINE] (required): Specifies the distance algorithm.

See Vector Field Format for more details and examples.

The KNN search algorithm operates to locate vectors that are the nearest to the query vector, i.e., looking for the smallest distance value. The computation of the distance metrics is adjusted from their classical definitions in order to posses this property. This table shows the actual computation that Search uses when computing the distance between two vectors: $X$ and $Y$.

Field options

SORTABLE (optional): This parameter is not required. Any field may be used with SORTBY whether or not it is declared SORTABLE. It is recorded on the attribute and reported by FT.INFO, but does not otherwise affect indexing or query behavior.

• UNF (optional): Only valid immediately after SORTABLE. In RediSearch this keeps the sort value of a SORTABLE field in its original form instead of converting it to lowercase. SORTBY already compares the stored field value directly, so this has no effect beyond being reported by FT.INFO.

Examples

HNSW example:

FT.CREATE my_index_name SCHEMA my_hash_field_key VECTOR HNSW 10 TYPE FLOAT32 DIM 20 DISTANCE_METRIC COSINE M 4 EF_CONSTRUCTION 100

Result:

OK

FLAT example:

FT.CREATE my_index_name SCHEMA my_hash_field_key VECTOR Flat TYPE FLOAT32 DIM 20 DISTANCE_METRIC COSINE INITIAL_CAP 15000

Result:

OK

HNSW example with a numeric field:

FT.CREATE my_index_name SCHEMA my_vector_field_key VECTOR HNSW 10 TYPE FLOAT32 DIM 20 DISTANCE_METRIC COSINE M 4 EF_CONSTRUCTION 100 my_numeric_field_key NUMERIC

Result:

OK

HNSW example with multiple tag and numeric fields

FT.CREATE my_index_name SCHEMA my_vector_field_key VECTOR HNSW          \
    10 TYPE FLOAT32 DIM 20 DISTANCE_METRIC COSINE M 4 EF_CONSTRUCTION   \
    100 my_tag_field_key_1 TAG SEPARATOR '@' CASESENSITIVE              \
    my_numeric_field_key_1 NUMERIC my_numeric_field_key_2 NUMERIC my_tag_field_key_2 TAG

Result:

OK

RESP2 Reply

Simple string reply: OK.

RESP3 Reply

Simple string reply: OK.

If an error occurs during the index creation, an error is returned.

History