A busca vetorial com o Tablestore SDK for Java retorna os dados mais próximos em um índice de busca por similaridade de vetores e oferece suporte a limiares de pontuação, contagem de candidatos e filtros não vetoriais.
Pré-requisitos
Instale o Tablestore SDK for Java e inicialize o cliente. A busca vetorial requer a versão 5.17.0 ou posterior.
Para configurar
minScoreounumCandidates, use a versão 5.17.5 ou posterior.
Descrição do recurso
A busca vetorial executa uma pesquisa de vizinho mais próximo aproximado (ANN) entre um vetor de consulta e os vetores em um campo Vector. O Tablestore pontua os resultados com a métrica de distância configurada na criação do índice de busca e retorna os dados mais próximos. Ao contrário das consultas que correspondem a valores de campos, a busca vetorial determina a similaridade com base na distância entre os vetores.
Chame search e defina query como KnnVectorQuery.
SearchResponse search(SearchRequest request)O exemplo a seguir recupera os três vetores no campo embedding mais próximos de [1.0, 0.0, 0.0, 0.0]. Os resultados são classificados por pontuação em ordem decrescente.
String tableName = "example_table";
String indexName = "example_index";
KnnVectorQuery query = new KnnVectorQuery();
query.setFieldName("embedding");
query.setTopK(3);
query.setFloat32QueryVector(new float[]{1.0f, 0.0f, 0.0f, 0.0f});
SearchQuery searchQuery = new SearchQuery();
searchQuery.setQuery(query);
searchQuery.setLimit(3);
searchQuery.setSort(new Sort(Collections.singletonList(new ScoreSort())));
SearchRequest request = new SearchRequest(tableName, indexName, searchQuery);
SearchRequest.ColumnsToGet columnsToGet = new SearchRequest.ColumnsToGet();
columnsToGet.setReturnAll(true);
request.setColumnsToGet(columnsToGet);
SearchResponse response = client.search(request);
for (SearchHit hit : response.getSearchHits()) {
System.out.println(hit.getScore() + ": " + hit.getRow());
}Há limites para o número e as dimensões dos campos vetoriais e para topK. Para obter detalhes, consulte Search index limits.
Parâmetros
Solicitação de busca
request é um objeto SearchRequest que contém os seguintes parâmetros.
|
Nome |
Tipo |
Descrição |
|
tableName (obrigatório) |
String |
Nome da tabela. |
|
indexName (obrigatório) |
String |
Nome do índice de busca. |
|
searchQuery (obrigatório) |
SearchQuery |
Condição de consulta e configurações comuns de consulta. |
|
columnsToGet (opcional) |
SearchRequest.ColumnsToGet |
Configurações das colunas retornadas. Se este parâmetro não for configurado, apenas as colunas de chave primária serão retornadas. |
|
timeoutInMillisecond (opcional) |
int |
Tempo limite da consulta no nível da solicitação, em milissegundos. Padrão: |
|
routingValues (opcional) |
|
Valores de chave primária dos campos de roteamento personalizados. Deixe este parâmetro indefinido se o roteamento personalizado não estiver configurado. |
Configuração da consulta
request.searchQuery é um objeto SearchQuery que contém os seguintes parâmetros.
|
Nome |
Tipo |
Descrição |
|
query (obrigatório) |
Query |
Condição da consulta. Defina este parâmetro como |
|
offset (opcional) |
Integer |
Posição inicial da consulta. |
|
limit (opcional) |
Integer |
Número máximo de linhas a retornar. Se definido como |
|
highlight (opcional) |
Highlight |
Configurações de resumo e destaque. Campos vetoriais não oferecem suporte a resumo e destaque. |
|
collapse (opcional) |
Collapse |
Configuração de colapso para deduplicar resultados com base em uma coluna especificada. |
|
sort (opcional) |
Sort |
Ordem de classificação dos resultados. Use |
|
trackTotalCount (opcional) |
int |
Número máximo de linhas correspondentes a contar. Padrão: |
|
filter (opcional) |
SearchFilter |
Filtro aplicado aos resultados de |
|
aggregationList (opcional) |
|
Configurações de agregação. |
|
groupByList (opcional) |
|
Configurações de agrupamento. |
|
token (opcional) |
byte[] |
Token de paginação. Defina este parâmetro com o valor de |
Condição de consulta vetorial
request.searchQuery.query é um objeto KnnVectorQuery que contém os seguintes parâmetros.
|
Nome |
Tipo |
Descrição |
|
fieldName (obrigatório) |
String |
Nome do campo vetorial. O campo deve ser do tipo Vector e a dimensão do vetor de consulta deve corresponder à dimensão configurada quando você criou o índice de busca. |
|
topK (obrigatório) |
Integer |
Quantidade de vetores mais próximos a recuperar. Máximo: |
|
float32QueryVector (obrigatório) |
float[] |
Vetor de consulta Float32 usado para calcular a similaridade. O comprimento do array deve corresponder à dimensão do campo vetorial. |
|
filter (opcional) |
Query |
Condições de consulta não vetoriais que os resultados da busca vetorial também devem atender. É possível combinar vários objetos |
|
weight (opcional) |
Float |
Peso de relevância da consulta vetorial. O valor deve ser maior ou igual a |
|
minScore (opcional) |
Float |
Limiar mínimo de pontuação. O valor deve ser maior ou igual a |
|
numCandidates (opcional) |
Integer |
Número de candidatos acessados em cada partição de índice durante o cálculo dos vizinhos mais próximos. Valores válidos: |
Colunas retornadas
request.columnsToGet é um objeto SearchRequest.ColumnsToGet que contém os seguintes parâmetros.
|
Nome |
Tipo |
Descrição |
|
columns (opcional) |
|
Colunas de atributo a retornar. Configure este parâmetro somente se |
|
returnAll (opcional) |
boolean |
Especifica se todas as colunas de atributo da tabela devem ser retornadas. Padrão: |
|
returnAllFromIndex (opcional) |
boolean |
Especifica se todas as colunas de atributo indexadas devem ser retornadas. Padrão: |
Resposta
Resposta da busca
search retorna um objeto SearchResponse. A tabela a seguir descreve os campos principais.
|
Nome |
Tipo |
Descrição |
|
totalCount |
long |
Número de linhas correspondentes. Chame |
|
rows |
|
Linhas retornadas por esta consulta. Chame |
|
searchHits |
|
Acertos da consulta. Chame |
|
nextToken |
byte[] |
Token para a próxima página. Chame |
|
isAllSuccess |
boolean |
Indica se todas as partições de índice foram consultadas. Chame |
Acerto da busca
Cada elemento em response.searchHits[] é um objeto SearchHit que contém os seguintes campos principais.
|
Nome |
Tipo |
Descrição |
|
row |
Row |
Linha correspondente. Chame |
|
score |
Double |
Pontuação da consulta vetorial. Chame |
Exemplos
Filtrar por condições não vetoriais e pontuação mínima
Use filter para exigir que os vizinhos mais próximos atendam a condições de consulta não vetoriais e use minScore para excluir dados cuja pontuação não seja maior que o limiar. O exemplo a seguir retorna apenas dados em que category é book, price é menor que 4 e a pontuação vetorial é maior que 0.6.
KnnVectorQuery filteredQuery = new KnnVectorQuery();
filteredQuery.setFieldName("embedding");
filteredQuery.setTopK(10);
filteredQuery.setFloat32QueryVector(
new float[]{1.0f, 0.0f, 0.0f, 0.0f});
filteredQuery.setMinScore(0.6f);
filteredQuery.setFilter(QueryBuilders.bool()
.must(QueryBuilders.term("category", "book"))
.must(QueryBuilders.range("price").lessThan(4)));
SearchQuery searchQuery = new SearchQuery();
searchQuery.setQuery(filteredQuery);
searchQuery.setLimit(10);Ajustar a contagem de candidatos
Defina numCandidates para expandir o conjunto de candidatos acessado em cada partição de índice durante o cálculo dos vizinhos mais próximos. O exemplo a seguir recupera os três vetores mais próximos a partir de quatro candidatos.
KnnVectorQuery candidateQuery = new KnnVectorQuery();
candidateQuery.setFieldName("embedding");
candidateQuery.setTopK(3);
candidateQuery.setFloat32QueryVector(
new float[]{1.0f, 0.0f, 0.0f, 0.0f});
candidateQuery.setNumCandidates(4);
SearchQuery candidateSearchQuery = new SearchQuery();
candidateSearchQuery.setQuery(candidateQuery);
candidateSearchQuery.setLimit(3);