Module: Valkey::Commands::VectorSearchCommands

Included in:
Valkey::Commands
Defined in:
lib/valkey/commands/vector_search_commands.rb

Overview

This module contains commands related to RediSearch Vector Search.

RediSearch provides secondary indexing, full-text search, and vector similarity search capabilities on top of Redis/Valkey. These commands require the RediSearch module to be loaded.

See Also:

Instance Method Summary collapse

Instance Method Details

#ft(subcommand, *args, **options) ⇒ Object

Convenience method for FT.* commands.

Examples:

List indexes

valkey.ft(:list)
  # => ["idx1", "idx2"]

Create an index

valkey.ft(:create, "myIndex", "SCHEMA", "title", "TEXT")
  # => "OK"

Search an index

valkey.ft(:search, "myIndex", "hello")
  # => [results]

Parameters:

  • subcommand (String, Symbol) —

    the subcommand (list, create, search, etc.)

  • args (Array) —

    arguments for the subcommand

  • options (Hash) —

    options for the subcommand

Returns:

  • (Object) —

    depends on subcommand



258
259
260
261
262
263
264
265
266
267
268
 
# File 'lib/valkey/commands/vector_search_commands.rb', line 258

def ft(subcommand, *args, **options)
  subcommand = subcommand.to_s.downcase.gsub("-", "_")

  if args.empty? && options.empty?
    send("ft_#{subcommand}")
  elsif options.empty?
    send("ft_#{subcommand}", *args)
  else
    send("ft_#{subcommand}", *args, **options)
  end
end

#ft_aggregate(index, query, *args) ⇒ Array

Run a search query with aggregations.

Examples:

Perform an aggregation query

valkey.ft_aggregate("myIndex", "*", "GROUPBY", "1", "@category", "REDUCE", "COUNT", "0", "AS", "count")
  # => [[1, ["category", "electronics", "count", "5"]]]

Parameters:

  • index (String) —

    the index name to search

  • query (String) —

    the search query

  • args (Array<String>) —

    additional query arguments (GROUPBY, REDUCE, etc.)

Returns:

  • (Array) —

    aggregation results

See Also:



38
39
40
41
 
# File 'lib/valkey/commands/vector_search_commands.rb', line 38

def ft_aggregate(index, query, *args)
  command_args = [index, query] + args
  send_command(RequestType::FT_AGGREGATE, command_args)
end

#ft_alias_add(alias_name, index) ⇒ String

Add an alias to an index.

Examples:

Add an alias to an index

valkey.ft_alias_add("myAlias", "myIndex")
  # => "OK"

Parameters:

  • alias (String) —

    the alias name

  • index (String) —

    the index name

Returns:

  • (String) —

    “OK” on success

See Also:



54
55
56
 
# File 'lib/valkey/commands/vector_search_commands.rb', line 54

def ft_alias_add(alias_name, index)
  send_command(RequestType::FT_ALIAS_ADD, [alias_name, index])
end

#ft_alias_del(alias_name) ⇒ String

Delete an alias from an index.

Examples:

Delete an alias

valkey.ft_alias_del("myAlias")
  # => "OK"

Parameters:

  • alias (String) —

    the alias name to delete

Returns:

  • (String) —

    “OK” on success

See Also:



68
69
70
 
# File 'lib/valkey/commands/vector_search_commands.rb', line 68

def ft_alias_del(alias_name)
  send_command(RequestType::FT_ALIAS_DEL, [alias_name])
end

#ft_alias_list ⇒ Array<String>

List all existing aliases.

Examples:

List all aliases

valkey.ft_alias_list
  # => ["alias1", "alias2"]

Returns:

  • (Array<String>) —

    array of alias names

See Also:



81
82
83
 
# File 'lib/valkey/commands/vector_search_commands.rb', line 81

def ft_alias_list
  send_command(RequestType::FT_ALIAS_LIST)
end

#ft_alias_update(alias_name, index) ⇒ String

Update an alias to point to a different index.

Examples:

Update an alias

valkey.ft_alias_update("myAlias", "newIndex")
  # => "OK"

Parameters:

  • alias (String) —

    the alias name

  • index (String) —

    the new index name

Returns:

  • (String) —

    “OK” on success

See Also:



96
97
98
 
# File 'lib/valkey/commands/vector_search_commands.rb', line 96

def ft_alias_update(alias_name, index)
  send_command(RequestType::FT_ALIAS_UPDATE, [alias_name, index])
end

#ft_create(index, *args) ⇒ String

Create a search index with the given schema.

Examples:

Create a basic index

valkey.ft_create("myIndex", "SCHEMA", "title", "TEXT", "price", "NUMERIC")
  # => "OK"

Create an index with vector field

valkey.ft_create("vecIndex", "ON", "HASH", "PREFIX", "1", "doc:",
                 "SCHEMA", "embedding", "VECTOR", "HNSW", "6",
                 "TYPE", "FLOAT32", "DIM", "128", "DISTANCE_METRIC", "COSINE")
  # => "OK"

Parameters:

  • index (String) —

    the index name

  • args (Array<String>) —

    schema definition and options

Returns:

  • (String) —

    “OK” on success

See Also:



117
118
119
120
 
# File 'lib/valkey/commands/vector_search_commands.rb', line 117

def ft_create(index, *args)
  command_args = [index] + args
  send_command(RequestType::FT_CREATE, command_args)
end

#ft_drop_index(index, dd: false) ⇒ String

Drop an index and optionally delete all documents.

Examples:

Drop an index without deleting documents

valkey.ft_drop_index("myIndex")
  # => "OK"

Drop an index and delete all documents

valkey.ft_drop_index("myIndex", dd: true)
  # => "OK"

Parameters:

  • index (String) —

    the index name

  • dd (Boolean) (defaults to: false) —

    whether to delete documents (DD flag)

Returns:

  • (String) —

    “OK” on success

See Also:



137
138
139
140
141
 
# File 'lib/valkey/commands/vector_search_commands.rb', line 137

def ft_drop_index(index, dd: false)
  args = [index]
  args << "DD" if dd
  send_command(RequestType::FT_DROP_INDEX, args)
end

#ft_explain(index, query, *args) ⇒ String

Explain how a query is parsed and executed.

Examples:

Explain a query

valkey.ft_explain("myIndex", "@title:hello @price:[0 100]")
  # => "INTERSECT {\n  @title:hello\n  @price:[0 100]\n}\n"

Parameters:

  • index (String) —

    the index name

  • query (String) —

    the search query

  • args (Array<String>) —

    additional query arguments

Returns:

  • (String) —

    query execution plan

See Also:



155
156
157
158
 
# File 'lib/valkey/commands/vector_search_commands.rb', line 155

def ft_explain(index, query, *args)
  command_args = [index, query] + args
  send_command(RequestType::FT_EXPLAIN, command_args)
end

#ft_explain_cli(index, query, *args) ⇒ String

Explain how a query is parsed and executed (CLI-formatted output).

Examples:

Explain a query in CLI format

valkey.ft_explain_cli("myIndex", "@title:hello")
  # => formatted query plan

Parameters:

  • index (String) —

    the index name

  • query (String) —

    the search query

  • args (Array<String>) —

    additional query arguments

Returns:

  • (String) —

    formatted query execution plan

See Also:



172
173
174
175
 
# File 'lib/valkey/commands/vector_search_commands.rb', line 172

def ft_explain_cli(index, query, *args)
  command_args = [index, query] + args
  send_command(RequestType::FT_EXPLAIN_CLI, command_args)
end

#ft_info(index) ⇒ Array

Get information about an index.

Examples:

Get index info

valkey.ft_info("myIndex")
  # => ["index_name", "myIndex", "fields", [...], ...]

Parameters:

  • index (String) —

    the index name

Returns:

  • (Array) —

    index information as array of key-value pairs

See Also:



187
188
189
 
# File 'lib/valkey/commands/vector_search_commands.rb', line 187

def ft_info(index)
  send_command(RequestType::FT_INFO, [index])
end

#ft_list ⇒ Array<String>

List all available indexes.

Examples:

List all indexes

valkey.ft_list
  # => ["idx1", "idx2"]

Returns:

  • (Array<String>) —

    array of index names

See Also:



22
23
24
 
# File 'lib/valkey/commands/vector_search_commands.rb', line 22

def ft_list
  send_command(RequestType::FT_LIST)
end

#ft_profile(index, query_type, *args) ⇒ Array

Profile a search or aggregation query.

Examples:

Profile a search query

valkey.ft_profile("myIndex", "SEARCH", "QUERY", "@title:hello")
  # => [execution time, results]

Profile an aggregation query

valkey.ft_profile("myIndex", "AGGREGATE", "QUERY", "*", "GROUPBY", "1", "@category")
  # => [execution time, results]

Parameters:

  • index (String) —

    the index name

  • query_type (String) —

    either “SEARCH” or “AGGREGATE”

  • args (Array<String>) —

    query arguments

Returns:

  • (Array) —

    profiling results with execution time and query results

See Also:



207
208
209
210
 
# File 'lib/valkey/commands/vector_search_commands.rb', line 207

def ft_profile(index, query_type, *args)
  command_args = [index, query_type] + args
  send_command(RequestType::FT_PROFILE, command_args)
end

#ft_search(index, query, *args) ⇒ Array

Search an index with a query.

Examples:

Basic search

valkey.ft_search("myIndex", "hello world")
  # => [1, "doc1", ["title", "hello world"]]

Search with options

valkey.ft_search("myIndex", "@title:hello", "LIMIT", "0", "10", "RETURN", "2", "title", "price")
  # => [total_results, doc_id, [field1, value1, field2, value2], ...]

Vector similarity search

valkey.ft_search("vecIndex", "*=>[KNN 5 @embedding $vec]",
                 "PARAMS", "2", "vec", vector_blob,
                 "RETURN", "1", "__embedding_score",
                 "DIALECT", "2")
  # => [results_count, doc_id, ["__embedding_score", "0.95"], ...]

Parameters:

  • index (String) —

    the index name

  • query (String) —

    the search query

  • args (Array<String>) —

    additional query arguments (LIMIT, RETURN, SORTBY, etc.)

Returns:

  • (Array) —

    search results with total count and matching documents

See Also:



235
236
237
238
 
# File 'lib/valkey/commands/vector_search_commands.rb', line 235

def ft_search(index, query, *args)
  command_args = [index, query] + args
  send_command(RequestType::FT_SEARCH, command_args)
end