Tair (Redis® OSS-Compatible):Vetor

Item

Descrição

Sintaxe

TVS.CREATEINDEX index_name dims algorithm distance_method [algo_param_key algo_param_value] ...

Complexidade de tempo

O(1)

Descrição do comando

Cria um índice vetorial, especificando o algoritmo para construção e consulta do índice, bem como a função de distância. O índice só pode ser excluído com o comando TVS.DELINDEX.

Parâmetros

• index_name: O nome do índice vetorial.

• dims: A dimensão do vetor. Todos os vetores inseridos no índice devem ter a mesma dimensão. O valor deve estar no intervalo [1, 32768].

• algorithm: O algoritmo para construção e consulta do índice. Valores válidos:

  • FLAT: Executa consultas utilizando busca por força bruta, sem criar um índice separado. Este algoritmo é adequado para pequenos conjuntos de dados com menos de 10.000 registros.

  • HNSW: Constrói um índice baseado em grafo HNSW para consultas. Recomendado para grandes conjuntos de dados.

• distance_method: O método para calcular a distância entre vetores. Valores válidos:

  • L2: A distância euclidiana ao quadrado.

  • IP: O produto interno. A distância é calculada como 1 - inner product.

  • COSINE: A distância do cosseno. A distância é calculada como 1 - cosine similarity. Ao usar a distância do cosseno, os vetores de entrada são convertidos em vetores unitários (normalização L2). Consequentemente, os vetores retornados podem não ser idênticos aos vetores originais.

  • JACCARD: A distância de Jaccard. A distância é calculada como 1 - Jaccard coefficient. Requer que o parâmetro data_type esteja definido como BINARY.

• algo_param_key e algo_param_value:

  • data_type: O tipo de dados do vetor denso. Valores válidos:

    • FLOAT32 (padrão): Um número de ponto flutuante de precisão simples de 4 bytes.

    • FLOAT16: Um número de ponto flutuante de meia precisão de 2 bytes, em conformidade com o padrão IEEE 754-2008. Este tipo de dados pode reduzir o uso de armazenamento para vetores, mas pode resultar em alguma perda de precisão. O intervalo de valores para FLOAT16 é [-65519, 65519].

    • BINARY: Um vetor binário contendo apenas 0s e 1s. Este tipo de dados só pode ser usado com a função de distância de Jaccard.

  • Parâmetros específicos para índices HNSW:

    • ef_construct: O tamanho da lista dinâmica usada durante a construção do índice com o algoritmo HNSW. O valor padrão é 100 e o intervalo válido é [1, 1000]. Um valor maior geralmente melhora a precisão da consulta, mas reduz o desempenho.

    • M: O número máximo de conexões de saída para cada nó em cada camada do grafo. O valor padrão é 16 e o intervalo válido é [1, 100]. Um valor maior geralmente melhora a precisão da consulta, mas reduz o desempenho.

    • auto_gc: Ativa ou desativa a recuperação automática de espaço do índice. Os valores válidos são false (padrão) e true. Este recurso exige que a versão secundária da instância seja 6.2.8.2 ou posterior. Índices HNSW usam exclusão marcada. Ativar esse recurso permite a recuperação automática de espaço, o que reduz o uso de memória, mas pode afetar o desempenho de consultas de vizinhos mais próximos. Recomendamos ativar este recurso para cenários sensíveis ao uso de memória.

  • Parâmetros específicos para índices híbridos:

    • Para criar um índice invertido em um campo de tag específico, você deve especificar o nome do campo e seu tipo de dados.

      Use a sintaxe inverted_index_<field_name> int|long|float|double|string para criar um índice invertido no field_name. Os tipos de dados suportados são int, long, float, double e string. As palavras-chave field_name e de tipo de dados devem estar em minúsculas.

      Por exemplo, para criar um índice invertido em um campo chamado productname do tipo String, use inverted_index_productname string.

    • lexical_algorithm: O algoritmo de busca de texto completo.

      • bm25: O algoritmo BM25 (Okapi BM25), adequado para busca de texto completo.

        • Ao gravar dados posteriormente usando TVS.HSET, defina o attribute_key como TEXT (deve estar em maiúsculas). Um índice de texto completo será então construído automaticamente no attribute_value correspondente.

        • Você fornece o texto original e o Tair constrói o índice.

      • vector: O algoritmo vetorial, adequado para vetores esparsos.

        Você deve codificar o texto original (embedding) e fornecer o vetor esparso. O formato dos dados é "[[,],[,],...]", onde index é um uint32_t e value é um Float que representa o peso ou frequência do termo.

    • Se você definir lexical_algorithm como bm25, também poderá configurar os seguintes parâmetros.

      • analyzer: O analisador. Atualmente, jieba (padrão) e ik_smart são suportados.

      • k1: Controla a saturação da frequência de termos no algoritmo BM25. O valor deve ser maior que 0. O valor padrão é 1.2.

      • b: Controla a influência do comprimento do documento no algoritmo BM25. O valor deve estar no intervalo [0, 1]. O valor padrão é 0.75.

    • Se você definir lexical_algorithm como vector, também poderá configurar os seguintes parâmetros.

      • lexical_use_hnsw: Especifica se deve usar um índice HNSW para vetores esparsos. Valores válidos: 1 (usar índice HNSW) e 0 (padrão, usar índice invertido).

      • lexical_hnsw_m: Quando lexical_use_hnsw está definido como 1, este parâmetro especifica o valor M para o índice HNSW, conforme descrito em Parâmetros específicos para índices HNSW acima.

      • lexical_hnsw_ef_construct: Quando lexical_use_hnsw está definido como 1, este parâmetro especifica o valor ef_construct para o índice HNSW, conforme descrito em Parâmetros específicos para índices HNSW acima.

    • hybrid_ratio: O peso padrão para busca vetorial em uma consulta. O valor deve ser um float no intervalo [0, 1]. O valor padrão é 0.5. O peso para busca de texto completo é calculado como 1 - hybrid_ratio.

Valor de retorno

• Retorna OK em caso de sucesso.

• Caso contrário, retorna uma mensagem de erro.

Exemplo

Comandos de exemplo:

# Create a vector index with a vector dimension of 2, the HNSW algorithm, the Jaccard distance function, and the BINARY data type.
TVS.CREATEINDEX index_name0 2 HNSW JACCARD data_type BINARY

# Create a vector index with a vector dimension of 2, the HNSW algorithm, the L2 distance function, and the FLOAT32 data type.
TVS.CREATEINDEX index_name1 2 HNSW L2 

# Create a vector index with a vector dimension of 2, the FLAT algorithm, the IP distance function, and the FLOAT32 data type.
TVS.CREATEINDEX index_name2 2 FLAT IP 

# Create a vector index with a vector dimension of 2, the FLAT algorithm, the Jaccard distance function, and the BINARY data type.
TVS.CREATEINDEX index_name3 2 FLAT JACCARD data_type BINARY

# Create a hybrid index combining HNSW vector search with bm25 full-text search.
TVS.CREATEINDEX index_name4 2 HNSW IP lexical_algorithm bm25 inverted_index_productname string

# Create a sparse vector index with a vector dimension of 2, the IP distance function, and an HNSW index.
TVS.CREATEINDEX index_name5 2 HNSW IP lexical_algorithm vector lexical_use_hnsw 1 lexical_hnsw_m 8 lexical_hnsw_ef_construct 100

Saída de exemplo:

OK

Item

Descrição

Sintaxe

TVS.GETINDEX index_name

Complexidade de tempo

O(1)

Descrição do comando

Recupera os metadados de um índice vetorial especificado.

Parâmetro

• index_name: O nome do índice vetorial.

Saída

• Em caso de sucesso, retorna os metadados do índice vetorial.

• Se o índice vetorial especificado não existir, retorna (empty array).

• Caso contrário, retorna uma mensagem de erro.

Exemplo

Execute primeiro os seguintes comandos:

TVS.CREATEINDEX my_index 2 HNSW L2 auto_gc true lexical_algorithm bm25
TVS.HSET my_index key0 VECTOR [1,2] creation_time 1730
TVS.HSET my_index key1 VECTOR [3,4] creation_time 1740
TVS.HSET my_index key2 VECTOR [5,6] creation_time 1750

Exemplo de comando para um índice HNSW:

TVS.GETINDEX my_index

Exemplo de saída:

 1) "lexical_term_count"   // The number of terms in the full-text index.
 2) "0"
 3) "lexical_record_count" // The number of documents in the full-text index.
 4) "0"
 5) "lexical_algorithm"    // The full-text indexing algorithm.
 6) "bm25"
 7) "auto_gc"              // Specifies if automatic memory space reclamation is enabled for the HNSW index.
 8) "1"
 9) "dimension"            // The vector dimension.
10) "2"
11) "attribute_data_size"  // The memory usage of attribute data, in bytes.
12) "3720"
13) "distance_method"      // The distance method.
14) "L2"
15) "data_type"            // The vector data type.
16) "FLOAT32"
17) "algorithm"            // The indexing algorithm.
18) "HNSW"
19) "index_data_size"      // The memory usage of vector data, in bytes.
20) "105128040"
21) "M"                    // The maximum number of outgoing neighbors for each node in the graph index structure. This parameter is returned only for HNSW indexes.
22) "16"
23) "data_count"           // The number of user records.
24) "3"
25) "current_record_count" // The total number of vectors.
26) "3"
27) "ef_construct"         // The size of the dynamic array used during index construction. This parameter is returned only for HNSW indexes.
28) "100"
29) "inverted_index_productname" // Information about the inverted index, including the field name, data type, and count.
30) "field: productname, type: string, size: 1"
31) "delete_record_count"  // The number of vectors to be deleted.
32) "0"

Item

Descrição

Sintaxe

TVS.DELINDEX index_name

Complexidade de tempo

O(N), onde N é o número de chaves no índice vetorial.

Descrição

Exclui um índice vetorial especificado e todos os dados que ele contém.

Parâmetro

• index_name: O nome do índice vetorial.

Valor de retorno

• Retorna 1 se o índice vetorial for excluído com sucesso.

• Retorna 0 se o índice especificado não existir.

• Caso contrário, retorna uma mensagem de erro.

Exemplo

Comando:

TVS.DELINDEX index_name0

Saída:

(integer) 1

Item

Descrição

Sintaxe

TVS.SCANINDEX cursor [MATCH pattern] [COUNT count]

Complexidade de tempo

O(N), onde N é o número de índices vetoriais na instância Tair.

Descrição do comando

Varre incrementalmente os índices vetoriais em uma instância Tair que correspondem aos critérios especificados.

Opções

• cursor: O cursor para a varredura. Use 0 para a varredura inicial. Nas varreduras subsequentes, utilize o cursor retornado pela chamada anterior.

• pattern: Um padrão no estilo glob usado para filtrar índices vetoriais por nome.

• count: Uma sugestão para o número de itens a serem varridos por iteração. O valor padrão é 10, mas o número real de itens retornados pode variar.

Saída

• Retorna um array contendo dois elementos:

  • O cursor para a próxima iteração. O valor "0" indica que a varredura foi concluída.

  • Um array com os nomes dos índices vetoriais (index_name) encontrados na varredura atual.

• Se o comando falhar, retorna uma mensagem de erro.

Exemplo

Exemplo de comando:

TVS.SCANINDEX 0

Exemplo de saída:

1) "0"
2) 1) "index_name1"
   2) "index_name0"
   3) "index_name2"
   4) "index_name3"

Exemplo de comando com padrão:

TVS.SCANINDEX 0 MATCH **name[0|1]

Exemplo de saída:

1) "0"
2) 1) "index_name1"
   2) "index_name0"

Item

Descrição

Sintaxe

TVS.HSET index_name key attribute_key attribute_value [attribute_key attribute_value] ...

Complexidade de tempo

A complexidade de tempo é O(1) se nenhum dado vetorial for criado ou atualizado; caso contrário, é O(log(N)), onde N é o número de chaves no índice vetorial.

Descrição do comando

Insere um registro de dados em um índice vetorial. Se já existir um registro com a key especificada, o registro existente será sobrescrito.

Parâmetros

• index_name: O nome do índice vetorial.

• key: A chave primária do registro de dados. Utilize o comando TVS.DEL para excluir o registro.

• attribute_key e attribute_value: Os atributos do registro, especificados como um ou mais pares chave-valor.

  • Para inserir dados vetoriais, defina attribute_key como a palavra-chave VECTOR (deve estar em maiúsculas). O attribute_value correspondente deve ser uma string de dados vetoriais compatível com a dimensão (dims) do índice vetorial. Por exemplo: VECTOR [1,2]. Cada chave pode ter apenas um atributo VECTOR. Se você definir esse atributo novamente para a mesma chave, os dados existentes serão sobrescritos.

  • Para inserir dados de texto, é necessário ter configurado os parâmetros de índice híbrido durante a criação do índice. Defina attribute_key como a palavra-chave TEXT (deve estar em maiúsculas). O attribute_value correspondente pode ser um dado de texto, como "TairVector is a proprietary vector database service developed by Tair", ou um embedding, como "[[2,0.221],[42,09688],...]".

  • Também é possível adicionar outros atributos personalizados ou metadados, como create_time 1663637425 (hora de criação) ou location Hangzhou (localização).

Valor de retorno

• Em caso de sucesso, o comando retorna o número de novos atributos adicionados ao registro de dados. Se apenas atributos existentes forem atualizados, retorna 0.

• Caso contrário, retorna uma mensagem de erro.

Exemplo

Exemplo de comando:

TVS.HSET my_index key5 VECTOR [7,8] TEXT "TairVector is a proprietary vector database service developed by Tair" create_time 1800

Exemplo de saída:

(integer) 3

Item

Descrição

Sintaxe

TVS.HGETALL index_name key

Complexidade de tempo

O(1)

Descrição do comando

Recupera todos os atributos e valores do registro de dados para a key especificada em um índice vetorial.

Parâmetro

• index_name: O nome do índice vetorial.

• key: A chave primária do registro de dados.

Valor de retorno

• Em caso de sucesso, retorna um array com atributos alternados e seus valores correspondentes para a key especificada.

• Se o índice vetorial especificado ou a key não existir, um (empty array) será retornado.

• Caso contrário, uma mensagem de erro será retornada.

Exemplo

Exemplo de comando:

TVS.HGETALL index_name0 key0

Exemplo de retorno:

1) "VECTOR"
2) "[1,2]"
3) "location"
4) "Hangzhou"
5) "create_time"
6) "1663637425"

Item

Descrição

Sintaxe

TVS.HMGET index_name key attribute_key [attribute_key ...]

Complexidade de tempo

O(1)

Descrição do comando

Retorna os valores das attribute keys especificadas para uma determinada key em um índice vetorial.

Parâmetros

• index_name: O nome do índice vetorial.

• key: A chave primária do registro.

• attribute_key: A chave ou chaves de atributo a serem recuperadas. Para recuperar o vetor, especifique a palavra-chave VECTOR (deve estar em maiúsculas). Para recuperar dados de texto brutos do índice de texto completo, especifique a palavra-chave TEXT (deve estar em maiúsculas).

Retornos

• Em caso de sucesso, retorna um array de valores para as attribute_keys especificadas, na ordem solicitada. Se uma chave de atributo não existir, o comando retorna nil em seu lugar.

• Caso contrário, o comando retorna uma mensagem de erro.

Exemplo

Exemplo de comando:

TVS.HMGET index_name0 key0 create_time location VECTOR TEXT

Exemplo de saída:

1) "1800"
2) "[7,8]"
3) "TairVector is a proprietary vector database service developed by Tair"

Item

Descrição

Sintaxe

TVS.DEL index_name key [key ...]

Complexidade de tempo

O(1)

Descrição do comando

Exclui o registro de dados especificado (key) do índice vetorial especificado.

Parâmetro

• index_name: O nome do índice vetorial.

• key: A chave primária de um registro de dados.

Valor de retorno

• Sucesso: Exclui o registro de dados especificado (key) e retorna a contagem de exclusões para a key.

• Retorna 0 se o índice vetorial não existir.

• Caso contrário, retorna uma mensagem de erro.

Exemplo

Exemplo de comando:

TVS.DEL index_name0 keyV

Exemplo de saída:

 (integer) 1

Item

Descrição

Sintaxe

TVS.HDEL index_name key attribute_key [attribute_key ...]

Complexidade de tempo

O(1)

Descrição do comando

Exclui uma ou mais attribute_keys e seus valores de um registro (key) em um índice vetorial.

Parâmetros

• index_name: O nome do índice vetorial.

• key: A chave primária do registro.

• attribute_key: A chave de atributo para a operação. É possível especificar várias chaves. Para excluir dados vetoriais, passe a palavra-chave VECTOR em maiúsculas. Para excluir dados completos do índice, passe a palavra-chave TEXT em maiúsculas.

Valor de retorno

• Retorna o número de attribute_keys removidas.

• Retorna 0 se o índice vetorial não existir.

• Retorna uma mensagem de erro nos demais casos.

Exemplo

Exemplo de comando:

TVS.HDEL index_name0 keyc VECTOR

Exemplo de saída:

 (integer) 1

Categoria

Descrição

Sintaxe

TVS.SCAN index_name cursor [MATCH pattern] [COUNT count] [FILTER filter_string] [VECTOR vector] [MAX_DIST max_distance]

Complexidade de tempo

O(N), onde N é o número de chaves no índice vetorial.

Descrição do comando

Varre registros de dados (identificados por key) que atendem às condições especificadas dentro de um determinado índice vetorial.

Parâmetros

• index_name: O nome do índice vetorial.

• cursor: O cursor para a varredura. Use 0 para a primeira varredura. Nas varreduras subsequentes, utilize o cursor retornado pela chamada anterior.

• pattern: Um padrão no estilo glob para correspondência de chaves.

• count: O número sugerido de itens a serem varridos em cada iteração. O valor padrão é 10. Não há garantia de que o número real de itens retornados seja exato.

• filter_string: As condições de filtro.

  • Suporta operadores como +, -, *, /, <, >, !=, (), && e ||. Os operadores > e < não suportam comparações de strings. Para incluir um literal de string no filtro, escape as aspas com uma barra invertida (\). Por exemplo: create_time > 1663637425 && location == \"Hangzhou\".

  • Separe os operadores de seus operandos com espaços. Por exemplo: "creation_time > 1735".

  • Comparações booleanas diretas, como flag == true, não são suportadas. Em vez disso, compare o valor como uma string: flag == \"true\".

• vector: O vetor de consulta. Este parâmetro deve ser usado junto com o parâmetro max_distance.

• max_distance: O limiar de distância máxima. Este parâmetro deve ser usado junto com o parâmetro vector. Quando ambos são especificados, o comando retorna apenas resultados cuja distância em relação ao vector de consulta seja menor que max_distance.

Valor de retorno

• Em caso de sucesso, o comando retorna um array com dois elementos:

  • O primeiro elemento é o cursor para a próxima iteração. O valor 0 indica que a varredura foi concluída.

  • O segundo elemento é um array com os nomes das keys dos registros de dados encontrados na iteração atual.

• Em caso de falha, o comando retorna uma mensagem de erro.

Exemplo

Exemplo de comando:

TVS.SCAN index_name0 0

Exemplo de valor de retorno:

1) "0"
2) 1) "key0"
   2) "keyV"

Categoria

Descrição

Sintaxe

TVS.HINCRBY index_name key attribute_key num

Complexidade de tempo

O(1)

Descrição do comando

Incrementa o valor inteiro de attribute_key para o registro de dados especificado (key) em um índice vetorial pelo valor de num.

Se attribute_key não existir, o comando o define como 0 antes de realizar o incremento. Se o valor de attribute_key não for um inteiro, o comando retorna um erro.

Parâmetros

• index_name: O nome do índice vetorial.

• key: O identificador de chave primária do registro de dados.

• attribute_key: A chave de atributo a ser incrementada.

• num: O valor inteiro a ser adicionado.

Valor de retorno

• Resposta inteira: O novo valor de attribute_key.

• Caso contrário, retorna uma mensagem de erro.

Exemplo

Exemplo de comando:

TVS.HINCRBY index_name0 key0 tv01 20

Exemplo de saída:

(integer) 20

Categoria

Descrição

Sintaxe

TVS.HINCRBYFLOAT index_name key attribute_key num

Complexidade de tempo

O(1)

Descrição do comando

Incrementa o valor de attribute_key de um registro de dados específico (key) pelo número de ponto flutuante num em um índice vetorial especificado.

Caso a attribute_key informada não exista, ela será criada com num como valor inicial.

Parâmetros

• index_name: Nome do índice vetorial.

• key: Identificador da chave primária do registro.

• attribute_key: Chave do atributo a ser incrementada.

• num: Valor de ponto flutuante a ser adicionado.

Valor retornado

• Em caso de sucesso, retorna o valor atualizado da chave do atributo.

• Se houver falha, uma mensagem de erro é exibida.

Exemplo

Comando de exemplo:

TVS.HINCRBYFLOAT index_name0 key0 tv02 9.34

Saída de exemplo:

"9.34"

Categoria

Descrição

Sintaxe

TVS.HPEXPIREAT index_name key milliseconds-timestamp

Complexidade de tempo

O(1)

Descrição do comando

Define o tempo absoluto de expiração, em milissegundos, para um registro de dados identificado por sua key dentro de um índice vetorial especificado.

Parâmetros

• index_name: Nome do índice vetorial.

• key: Chave primária do registro de dados.

• milliseconds-timestamp: Timestamp UNIX especificado em milissegundos. Se o timestamp estiver no passado, a key expira imediatamente.

Valor retornado

• Retorna 1 se o tempo limite for definido para uma key existente.

• Retorna 0 caso a key não exista.

• Nos demais casos, retorna uma exceção.

Exemplo

Comando de exemplo:

TVS.HPEXPIREAT index_name0 key1 16914619090000

Saída de exemplo:

(integer) 1

Item

Descrição

Sintaxe

TVS.HPEXPIRE index_name key milliseconds-timestamp

Complexidade de tempo

O(1)

Descrição do comando

Define um tempo relativo de expiração, em milissegundos, para uma key específica em um índice vetorial.

Parâmetros

• index_name: Nome do índice vetorial.

• key: Identificador da chave primária do vetor.

• milliseconds-timestamp: Tempo relativo de expiração, em milissegundos.

Valor retornado

• 1 se a expiração foi definida com sucesso.

• 0 caso a chave não exista.

• Um erro nas demais situações.

Exemplo

Comando de exemplo:

TVS.HPEXPIRE index_name0 key1 1000

Saída de exemplo:

(integer) 1

Categoria

Descrição

Sintaxe

TVS.HEXPIREAT index_name key timestamp

Complexidade de tempo

O(1)

Descrição do comando

Define um tempo absoluto de expiração para uma key específica em um índice vetorial, com precisão de segundos.

Opções

• index_name: Nome do índice vetorial.

• key: Chave primária do registro.

• timestamp: Timestamp UNIX em segundos. Se o timestamp estiver no passado, a key expira imediatamente.

Valor retornado

• Retorna 1 se o tempo limite for definido para a key.

• Retorna 0 caso a key não exista.

• Caso contrário, retorna uma mensagem de erro.

Exemplo

Exemplo de comando:

TVS.HEXPIREAT index_name0 key2 1691466981

Exemplo de retorno:

(integer) 1

Categoria

Descrição

Sintaxe

TVS.HEXPIRE index_name key timestamp

Complexidade de tempo

O(1)

Descrição do comando

Define um tempo relativo de expiração, em segundos, para um vetor específico (key) em um índice vetorial.

Parâmetros

• index_name: Nome do índice vetorial.

• key: Identificador da chave primária do vetor.

• timestamp: Tempo relativo de expiração, em segundos.

Saída

• Se o tempo limite for definido com sucesso para uma key existente: 1.

• Caso a key não exista: 0.

• Nas demais situações, uma mensagem de erro é retornada.

Exemplo

Comando de exemplo:

TVS.HEXPIRE index_name0 key2 100

Saída de exemplo:

(integer) 1

Categoria

Descrição

Sintaxe

TVS.HPTTL index_name key

Complexidade de tempo

O(1)

Descrição do comando

Retorna o TTL, em milissegundos, de um registro de dados específico (key) em um índice vetorial.

Parâmetros

• index_name: Nome do índice vetorial.

• key: Chave primária do registro de dados.

Valor retornado

• O TTL em milissegundos, caso a key exista e tenha um tempo de expiração definido.

• -1 se a key existir, mas não possuir tempo de expiração configurado.

• -2 quando a key ou o index_name não existem.

• Uma mensagem de erro.

Exemplo

Comando de exemplo:

TVS.HPTTL index_name0 key2

Saída de exemplo:

(integer) 65417

Categoria

Descrição

Sintaxe

TVS.HTTL index_name key

Complexidade de tempo

O(1)

Descrição do comando

Obtém o TTL em segundos de um registro de dados específico (key) em um índice vetorial informado.

Parâmetros

• index_name: Nome do índice vetorial.

• key: Chave primária do registro de dados.

Valor retornado

• O TTL restante em segundos, caso a key exista e possua tempo de expiração.

• -1, se a key existir, mas não tiver tempo de expiração.

• -2, quando a key ou o index_name não existem.

• Uma mensagem de exceção para qualquer outro erro.

Exemplo

Exemplo de comando:

TVS.HTTL index_name0 key2

Exemplo de retorno:

(integer) 58

Categoria

Descrição

Sintaxe

TVS.HPEXPIRETIME index_name key

Complexidade de tempo

O(1)

Descrição do comando

Retorna o tempo absoluto de expiração de um registro de dados específico (key) em um índice vetorial, como um timestamp Unix em milissegundos.

Parâmetro

• index_name: Nome do índice vetorial.

• key: Identificador da chave primária do registro de dados.

Valor retornado

• Se a key existir e tiver um tempo de expiração definido: O tempo absoluto de expiração como um timestamp Unix em milissegundos.

• Caso a key exista, mas sem tempo de expiração definido: -1.

• Quando a key ou o index_name não existem: -2.

• Nos demais casos: Uma mensagem de erro correspondente.

Exemplo

Comando de exemplo:

TVS.HPEXPIRETIME index_name0 key2

Saída de exemplo:

(integer) 1691473985764

Item

Descrição

Sintaxe

TVS.HEXPIRETIME index_name key

Complexidade de tempo

O(1)

Descrição do comando

Retorna o tempo absoluto de expiração de um registro de dados específico (key) em um índice vetorial como um timestamp Unix em segundos.

Parâmetros

• index_name: Nome do índice vetorial.

• key: Identificador da chave primária do registro de dados.

Saída

• Se a key existir e tiver um tempo de expiração definido, o valor corresponde ao tempo absoluto de expiração (timestamp Unix) em segundos.

• A key existe, mas não possui tempo de expiração: -1.

• Quando a key ou o index_name não existem, o comando retorna -2.

• Em outros cenários, o comando retorna uma mensagem de erro.

Exemplo

Comando de exemplo:

TVS.HEXPIRETIME index_name0 key2

Saída de exemplo:

(integer) 1691473985

Item

Descrição

Sintaxe

TVS.KNNSEARCH index_name topN vector [filter_string] [param_key param_value]

Complexidade de tempo

• Algoritmo HNSW: O(log(N))

• Algoritmo FLAT: O(N)

N representa o número de chaves no índice vetorial.

Descrição do comando

Executa uma consulta de vizinhos mais próximos para um vetor específico em um índice vetorial e retorna até topN resultados.

Parâmetros

• index_name: Nome do índice vetorial.

• topN: Quantidade de resultados a serem retornados. O valor deve estar no intervalo [1, 10000].

• vector: Valor do vetor usado para realizar a consulta de vizinhos mais próximos. Para executar apenas uma busca de texto completo em um índice híbrido, passe "" neste campo.

• filter_string: Condição de filtro.

  • Suporta operadores como +-*/<>!=()&&||. Comparações de string para maior ou menor que não são suportadas. Para incluir um literal de string no filtro, use o caractere de escape (\) nas aspas. Por exemplo: "create_time > 1663637425 && location == \"Hangzhou\"".

  • Os operadores devem ser separados de seus operandos por espaços. Exemplo: "creation_time > 1735".

  • Comparações booleanas diretas, como flag == true, não são suportadas. Em vez disso, compare o valor como uma string: flag == \"true\".

• param_key e param_value: Parâmetros operacionais da consulta, especificados como pares chave-valor. Os seguintes parâmetros são suportados:

  • ef_search: Tamanho da lista dinâmica para a busca. O valor padrão é 100, e o intervalo válido é [1, 1000]. Valores maiores geralmente melhoram a precisão da busca, mas aumentam a sobrecarga de desempenho. Este parâmetro é específico do algoritmo HNSW.

    Para um índice híbrido que utiliza um índice HNSW para vetores esparsos, use sparse_ef_search para especificar o parâmetro ef_search do índice de vetores esparsos.

  • MAX_DIST: Limite máximo de distância. Deve ser um float. Filtra chaves cuja distância em relação ao vetor de consulta seja maior que este valor.

  • TEXT: Texto de consulta para uma busca híbrida, podendo ser texto ou vetor. Se este parâmetro não for especificado ou for definido como "", nenhuma busca de texto completo será realizada, executando-se apenas a busca vetorial.

  • hybrid_ratio: Peso dos resultados da busca vetorial nesta consulta. O valor deve ser um float no intervalo [0, 1]. O padrão é o valor de hybrid_ratio definido durante a criação do índice. O peso da busca de texto completo é calculado como 1-hybrid_ratio.

  • Por padrão, o sistema utiliza a estratégia PostFilter, que executa a busca vetorial de k-vizinhos mais próximos (KNN) antes de aplicar o filtro escalar.

    • vector_filter_count: Número máximo de candidatos a filtrar nos resultados da busca vetorial. Padrão: 10.000.

      Na estratégia PostFilter, a busca é interrompida se filtrar mais candidatos do que esse número sem encontrar topN resultados.

    • fulltext_filter_count: Número máximo de candidatos a filtrar nos resultados da busca de texto completo. Padrão: 10.000.

      Na estratégia PostFilter, a busca é interrompida se filtrar mais candidatos do que esse número sem encontrar topN resultados.

    • Para usar a estratégia PreFilter, que aplica o filtro escalar com base no índice invertido antes da busca vetorial KNN, adicione o parâmetro search_policy scalar à sua consulta.

      Também é possível fornecer o parâmetro ivf_filter_count, que define o número máximo de registros a recuperar do índice invertido durante a etapa de pré-filtragem. O padrão é 10.000. Na estratégia PreFilter, se o número de registros correspondentes ao filtro escalar exceder esse valor, o sistema reverte para a estratégia PostFilter.

    Nota

    Na maioria dos casos, esses parâmetros padrão garantem baixa latência mantendo alta precisão. Você pode ajustá-los para solicitações específicas, mas esteja ciente de que valores maiores podem aumentar a latência da consulta.

Valor retornado

• Uma execução bem-sucedida retorna as keys dos vizinhos mais próximos e suas distâncias em relação ao vetor alvo, ordenadas da menor para a maior distância.

• Se o índice vetorial especificado não existir, o comando retorna um (empty array).

• Nos demais casos, retorna uma mensagem de erro.

Exemplos

TVS.CREATEINDEX my_index_k 2 HNSW L2 inverted_index_productname string
TVS.HSET my_index_k key0 VECTOR [1,2] creation_time 1730 productname "Aliyun"
TVS.HSET my_index_k key1 VECTOR [3,4] creation_time 1740 productname "other"
TVS.HSET my_index_k key2 VECTOR [5,6] creation_time 1750 productname "Aliyun"

Exemplo 1:

TVS.KNNSEARCH my_index_k 2 [3,3.1] "creation_time > 1735"

Resposta 1:

1) "key1"
2) "0.81000018119812012"
3) "key2"
4) "12.410000801086426"

Exemplo 2:

TVS.KNNSEARCH my_index_k 2 [3,3.1]  "creation_time > 1735 && productname ==  \"Aliyun\"" search_policy scala ivf_filter_count 15000

Resposta 2:

1) "key2"
2) "12.410000801086426"

Item

Descrição

Sintaxe

TVS.KNNSEARCHFIELD index_name topN vector field_count field_name [field_name ...] [filter_string] [param_key param_value]

Complexidade de tempo

• Algoritmo HNSW: O(log(N))

• Algoritmo FLAT: O(N)

N representa o número de chaves no índice vetorial.

Descrição do comando

Busca os vizinhos mais próximos de um vetor especificado em um índice vetorial. A lógica de pesquisa é idêntica à do TVS.KNNSEARCH, mas este comando também retorna atributos de tag.

Parâmetro

• index_name: Nome do índice vetorial.

• topN: Quantidade de resultados a retornar. O valor deve estar no intervalo [1, 10000].

• vector: Vetor de consulta para a busca de vizinhos mais próximos. Para executar apenas uma busca de texto completo em um índice híbrido, passe uma string vazia ("") neste parâmetro.

• field_count: Número de atributos de tag a retornar. Para retornar todos os atributos de tag, defina field_count como 0.

• field_name: Nomes dos atributos de tag a retornar. A quantidade de nomes deve corresponder ao valor de field_count.

• filter_string: Condição de filtro. Para mais informações, consulte TVS.KNNSEARCH.

• param_key e param_value: Parâmetros operacionais da consulta. Para mais informações, consulte TVS.KNNSEARCH.

Valor de retorno

• Em caso de sucesso, o comando retorna a key, a distância em relação ao vetor de consulta e os pares chave-valor dos atributos de tag para cada vizinho mais próximo. Os resultados são ordenados por distância em ordem crescente.

• Se o índice vetorial especificado não existir, o retorno será (empty array).

• Caso contrário, uma mensagem de erro é retornada.

Exemplo

TVS.CREATEINDEX my_index_k 2 HNSW L2
TVS.HSET my_index_k key0 VECTOR [1,2] creation_time 1730
TVS.HSET my_index_k key1 VECTOR [3,4] creation_time 1740
TVS.HSET my_index_k key2 VECTOR [5,6] creation_time 1750

Comando de exemplo:

TVS.KNNSEARCHFIELD my_index_k 2 [3,3.1] 0 "creation_time > 1735"

Saída de exemplo:

1) 1) "key1"
   2) "0.81000018119812012"
   3) "VECTOR"
   4) "[3,4]"
   5) "creation_time"
   6) "1740"
2) 1) "key2"
   2) "12.410000801086426"
   3) "VECTOR"
   4) "[5,6]"
   5) "creation_time"
   6) "1750"

Item

Descrição

Sintaxe

TVS.GETDISTANCE index_name vector key_count key [key, ...] [TOPN topN] [FILTER filter_string] [MAX_DIST max_distance]

Complexidade de tempo

• Algoritmo HNSW: O(log N)

• Algoritmo FLAT: O(N)

N representa o número de chaves no índice vetorial.

Descrição do comando

Localiza os vizinhos mais próximos de um vetor de consulta a partir de uma lista específica de chaves dentro de um índice vetorial.

Parâmetro

• index_name: Nome do índice vetorial.

• vector: Vetor de consulta.

• key_count: Quantidade de chaves candidatas.

• key: Nomes das chaves candidatas. A quantidade de chaves deve corresponder ao valor de key_count.

• TOPN: Número máximo de resultados a retornar. O valor padrão é key_count. O valor deve estar no intervalo [1, key_count].

• FILTER: Condição de filtro.

  • Suporta operadores como +-*/<>!=()&&||. Comparações de maior ou menor que não são suportadas para strings. Para incluir um literal de string, escape as aspas com uma barra invertida (\). Exemplo: create_time > 1663637425 && location == \"Hangzhou\".

  • Os operadores devem ser separados de seus operandos por espaços. Por exemplo, "creation_time > 1735".

  • Comparações booleanas diretas, como flag == true, não são suportadas. Em vez disso, compare o valor como uma string: flag == \"true\".

• MAX_DIST: Filtra as chaves cuja distância em relação ao vetor de consulta excede este valor.

Saída

• Retorna as chaves correspondentes e suas distâncias. Por padrão, os resultados seguem a mesma ordem das chaves fornecidas. Se TOPN for especificado, o comando retorna as topN chaves mais próximas e suas distâncias, classificadas da mais próxima para a mais distante.

• Retorna um (empty array) se o índice vetorial não existir.

• Para todos os outros erros, uma mensagem de erro é retornada.

Exemplo

TVS.CREATEINDEX my_index_k 2 HNSW L2
TVS.HSET my_index_k key0 VECTOR [1,2] creation_time 1730
TVS.HSET my_index_k key1 VECTOR [3,4] creation_time 1740
TVS.HSET my_index_k key2 VECTOR [5,6] creation_time 1750

Comando de exemplo:

TVS.GETDISTANCE my_index_k [1,1] 2 key1 key2

Saída de exemplo:

1) "key1"
2) "13"
3) "key2"
4) "41"

Item

Descrição

Sintaxe

TVS.MKNNSEARCH index_name topN vector_count vector [vector ...] [filter_string] [param_key param_value]

Complexidade de tempo

• Algoritmo HNSW: vector_count * O(log(N))

• Algoritmo FLAT: vector_count * O(N)

N representa o número de chaves no índice vetorial.

Descrição do comando

Realiza uma busca em lote pelos vizinhos mais próximos de múltiplos vetores em um índice vetorial especificado.

Parâmetros

• index_name: Nome do índice vetorial.

• topN: Quantidade de resultados a retornar para cada vetor de consulta. O valor deve estar no intervalo [1, 10000].

• vector_count : Número de vetores de consulta.

• vector: Um ou mais vetores para a busca de vizinhos mais próximos. Para executar apenas uma busca de texto completo em um índice híbrido, passe "" neste parâmetro.

• filter_string: Condição de filtro. Para mais informações, consulte a descrição em TVS.KNNSEARCH.

• param_key e param_value: Parâmetros de execução da consulta. Para mais informações, consulte a descrição em TVS.KNNSEARCH.

Valor de retorno

• Em caso de sucesso, o comando retorna vários arrays de resultados, um para cada vetor de consulta. Cada array contém as keys dos vizinhos mais próximos e suas distâncias, classificadas da mais próxima para a mais distante.

• Se o índice vetorial não existir, o comando retorna um (empty array).

• Caso contrário, o comando retorna uma mensagem de erro.

Exemplo

TVS.CREATEINDEX my_index_m 2 HNSW L2
TVS.HSET my_index_m key0 VECTOR [1,2] creation_time 1730
TVS.HSET my_index_m key1 VECTOR [3,4] creation_time 1740
TVS.HSET my_index_m key2 VECTOR [5,6] creation_time 1750

Comando de exemplo:

TVS.MKNNSEARCH my_index_m 2 2 [3,4] [5,6] "creation_time > 1735"

Saída de exemplo:

1) 1) "key1"
   2) "0"
   3) "key2"
   4) "8"
2) 1) "key2"
   2) "0"
   3) "key1"
   4) "8"

Item

Descrição

Sintaxe

TVS.MINDEXKNNSEARCH index_count index_name [index_name ...] topN vector [filter_string] [param_key param_value]

Complexidade de tempo

• Algoritmo HNSW: index_count * O(log(N))

• Algoritmo FLAT: index_count * O(N)

N representa o número de chaves no índice vetorial.

Descrição do comando

Busca os vizinhos mais próximos de um vetor especificado em vários índices vetoriais.

Parâmetro

• index_count: Quantidade de índices vetoriais.

• index_name: Nomes dos índices vetoriais.

• topN: Número de vizinhos mais próximos a retornar, variando de 1 a 10.000. O comando recupera os topN principais resultados de cada índice especificado, agrega-os e retorna os topN vizinhos mais próximos gerais do conjunto combinado.

• vector: Vetor de consulta para a busca de vizinhos mais próximos.

• filter_string: Condições de filtro. Para mais informações, consulte a descrição em TVS.KNNSEARCH.

• param_key e param_value: Parâmetros operacionais da consulta. Para mais informações, consulte a descrição em TVS.KNNSEARCH.

Saída

• Retorna um array com as keys dos vizinhos mais próximos e suas distâncias em relação ao vetor de consulta, classificados do mais próximo ao mais distante.

• Retorna um (empty array) se um índice vetorial especificado não existir.

• Caso contrário, retorna uma mensagem de erro.

Exemplo

TVS.CREATEINDEX my_index_mk 2 HNSW L2
TVS.HSET my_index_mk key0 VECTOR [1,2] creation_time 1730
TVS.HSET my_index_mk key1 VECTOR [3,4] creation_time 1740
TVS.HSET my_index_mk key2 VECTOR [5,6] creation_time 1750
TVS.CREATEINDEX my_index_mx 2 HNSW L2
TVS.HSET my_index_mx key5 VECTOR [8,7] creation_time 1730
TVS.HSET my_index_mx key6 VECTOR [6,5] creation_time 1740
TVS.HSET my_index_mx key7 VECTOR [4,3] creation_time 1750

Comando de exemplo:

TVS.MINDEXKNNSEARCH 2 my_index_mk my_index_mx 2 [0,0]

Saída de exemplo:

1) "key0"
2) "5"
3) "key7"
4) "25"

Categoria

Descrição

Sintaxe

TVS.MINDEXKNNSEARCHFIELD index_count index_name [index_name ...] topN vector field_count field_name [field_name ...] [filter_string] [param_key param_value]

Complexidade de tempo

• Algoritmo HNSW: index_count * O(log(N))

• Algoritmo FLAT: index_count * O(N)

N representa o número de chaves no índice vetorial.

Descrição do comando

Executa uma consulta de vizinhos mais próximos para um vetor especificado em vários índices vetoriais e, opcionalmente, retorna tags.

Parâmetros

• index_count: Quantidade de índices vetoriais.

• index_name: Nomes dos índices vetoriais.

• topN: Número de vizinhos mais próximos a retornar, variando de 1 a 10.000. O comando consulta os topN vizinhos mais próximos em cada índice vetorial, agrega esses resultados e então retorna os topN resultados gerais com as menores distâncias.

• vector: Vetor de entrada para a consulta de vizinhos mais próximos.

• field_count: Quantidade de tags a retornar. Para retornar todas as tags, defina field_count como 0.

• field_name: Nomes das tags a retornar. A quantidade de nomes fornecidos deve corresponder ao valor de field_count.

• filter_string: Condições de filtro. Para mais informações, consulte TVS.KNNSEARCH.

• param_key e param_value: Parâmetros de execução da consulta. Para mais informações, consulte TVS.KNNSEARCH.

Saída

• Em caso de sucesso, o comando retorna as keys dos vizinhos mais próximos, suas distâncias em relação ao vetor de consulta e seus respectivos pares chave-valor de tag. Os resultados são ordenados por distância em ordem crescente.

• Se um índice vetorial especificado não existir, o comando retorna um (empty array).

• Caso contrário, o comando retorna uma mensagem de erro.

Exemplo

TVS.CREATEINDEX my_index_mk 2 HNSW L2
TVS.HSET my_index_mk key0 VECTOR [1,2] creation_time 1730
TVS.HSET my_index_mk key1 VECTOR [3,4] creation_time 1740
TVS.HSET my_index_mk key2 VECTOR [5,6] creation_time 1750
TVS.CREATEINDEX my_index_mx 2 HNSW L2
TVS.HSET my_index_mx key5 VECTOR [8,7] creation_time 1730
TVS.HSET my_index_mx key6 VECTOR [6,5] creation_time 1740
TVS.HSET my_index_mx key7 VECTOR [4,3] creation_time 1750

Comando de exemplo:

TVS.MINDEXKNNSEARCHFIELD 2 my_index_mk my_index_mx 2 [0,0] 0

Saída de exemplo:

1) 1) "key0"
   2) "5"
   3) "my_index_mk"
   4) "VECTOR"
   5) "[1,2]"
   6) "creation_time"
   7) "1730"
2) 1) "key1"
   2) "25"
   3) "my_index_mk"
   4) "VECTOR"
   5) "[3,4]"
   6) "creation_time"
   7) "1740"

Item

Descrição

Sintaxe

TVS.MINDEXMKNNSEARCH index_count index_name [index_name ...] topN vector_count vector [vector ...] [filter_string] [param_key param_value]

Complexidade de tempo

• Algoritmo HNSW: index_count vector_count O(log(N))

• Algoritmo FLAT: index_count vector_count O(N)

N representa o número de chaves no índice vetorial.

Descrição do comando

Busca os vizinhos mais próximos de múltiplos vetores em vários índices vetoriais.

Parâmetros

• index_count: Quantidade de índices vetoriais.

• index_name: Nome de um índice vetorial.

• topN: Número de vizinhos mais próximos a retornar para cada vetor de consulta. O valor deve estar no intervalo [1, 10000]. Por padrão, o comando recupera os resultados topN de cada índice vetorial, agrega-os e retorna os resultados topN gerais com as menores distâncias.

• vector_count: Quantidade de vetores de consulta.

• vector: Vetor de consulta para a busca de vizinhos mais próximos.

• filter_string: Condições de filtro. Para mais informações, consulte TVS.KNNSEARCH.

• param_key e param_value: Parâmetros operacionais da consulta. Para mais informações, consulte TVS.KNNSEARCH.

Valor de retorno

• Em caso de sucesso, retorna um array de arrays de resultados na mesma ordem dos vetores de consulta. Cada array de resultado contém a key e a distância de cada vizinho mais próximo, classificados por distância do mais próximo ao mais distante.

• Se um índice vetorial especificado não existir, retorna um (empty array).

• Nos demais casos, retorna uma mensagem de erro.

Exemplo

TVS.CREATEINDEX my_index_mk 2 HNSW L2
TVS.HSET my_index_mk key0 VECTOR [1,2] creation_time 1730
TVS.HSET my_index_mk key1 VECTOR [3,4] creation_time 1740
TVS.HSET my_index_mk key2 VECTOR [5,6] creation_time 1750
TVS.CREATEINDEX my_index_mx 2 HNSW L2
TVS.HSET my_index_mx key5 VECTOR [8,7] creation_time 1730
TVS.HSET my_index_mx key6 VECTOR [6,5] creation_time 1740
TVS.HSET my_index_mx key7 VECTOR [4,3] creation_time 1750

Comando de exemplo:

TVS.MINDEXMKNNSEARCH 2 my_index_mk my_index_mx 2 2 [0,0] [3,3]

Saída de exemplo:

1) 1) "key0"
   2) "5"
   3) "key7"
   4) "25"
2) 1) "key1"
   2) "1"
   3) "key7"
   4) "1"