Todos los productos
Search
Centro de documentos

Tablestore:Uso de la consulta de vectores KNN

Última actualización: Oct 09, 2026

Este tema explica cómo usar las consultas de vectores de k vecinos más cercanos (KNN) en la consola de Tablestore o con los SDK de Tablestore.

API

Para ejecutar una consulta de vectores KNN, llame a la operación Search y establezca el tipo de consulta en KnnVectorQuery.

Parámetros

Parámetro

Obligatorio

Descripción

fieldName

Sí

El nombre del campo de vector.

topK

Sí

La cantidad de vecinos más cercanos que se devolverán. Para conocer el valor máximo, consulte Search index limits.

Importante

Un valor de K mayor incrementa la recuperación, pero también aumenta la latencia y el costo de la consulta.

float32QueryVector

Sí

El vector de consulta que se utiliza para la búsqueda por similitud.

minScore

No

El umbral mínimo de puntuación. Solo se devuelven las filas con una puntuación superior a este valor. El valor debe ser mayor o igual a 0. Valor predeterminado: 0.

filter

No

Un filtro que admite cualquier combinación de condiciones de consulta no vectoriales.

Procedimiento

Nota

Si tiene problemas con las consultas de vectores KNN, envíe un ticket.

Puede ejecutar una consulta de vectores KNN desde la consola de Tablestore o mediante un SDK. Antes de empezar, complete las siguientes tareas:

Uso de la consola

  1. Vaya a la pestaña Index Management.

    1. Inicie sesión en la consola de Table Store.

    2. En la barra de navegación superior, seleccione un resource group y una región.

    3. En la página Overview, haga clic en el nombre de la instancia o en Instance Management dentro de la columna Actions.

    4. En la pestaña Instance Details y dentro de la pestaña Data Table List, haga clic en el nombre de la tabla de datos o en Index Management en la columna Actions.

  2. En la pestaña Index Management, busque el Search Index deseado y haga clic en Search dentro de la columna Actions.

  3. En el cuadro de diálogo Search, configure los parámetros de consulta.

    1. De forma predeterminada, se devuelven todas las columnas. Si desea devolver columnas específicas, desactive Retrieve All Columns e introduzca los nombres de las columnas separados por comas.

      Nota

      Table Store devuelve de forma predeterminada las columnas de clave principal de la tabla de datos.

    2. Seleccione un operador lógico: And, Or o Not.

      Si selecciona And, la consulta devuelve los datos que cumplen todas las condiciones especificadas. Al elegir Or, devuelve los datos que cumplen como mínimo una de las condiciones. Con Not, devuelve los datos que no cumplen las condiciones indicadas.

    3. Seleccione un campo de vector y haga clic en Add.

    4. Establezca el tipo de consulta del campo de vector en KNN vector query (KnnVectorQuery) y, a continuación, introduzca el vector de consulta y el valor de topK.

      Introduzca el vector con el formato que se indica en la página.

    5. La ordenación está deshabilitada de forma predeterminada. Para ordenar los resultados por un campo específico, active Enable Sorting, agregue el campo de ordenación y configure el criterio correspondiente.

    6. La agregación está deshabilitada de forma predeterminada. Para aplicar una agregación estadística sobre un campo específico, active Enable Aggregation, agregue el campo para la agregación y configure los ajustes correspondientes.

  4. Haga clic en OK.

    Los resultados de la consulta se muestran en la pestaña Index Management.

Uso de un SDK

Importante

La función de consulta de vectores KNN está disponible en Tablestore SDK for Java 5.17.0 o posterior, en la versión más reciente de Tablestore SDK for Go, en Tablestore SDK for Python 5.4.4 o posterior y en Tablestore SDK for Node.js 5.5.0 o posterior.

Puede ejecutar una consulta de vectores KNN con Java SDK, Go SDK, Python SDK o Node.js SDK. En el siguiente ejemplo se usa el SDK de Java.

Importante

Antes de usar el SDK de Java para ejecutar una consulta de vectores KNN, debe inicializar el cliente. Para obtener más información, consulte Initialize a Tablestore client.

En el siguiente ejemplo se recuperan los 10 vecinos más cercanos a un vector dado, con una puntuación mínima de similitud de 0.1. Los resultados se filtran adicionalmente para incluir solo las filas donde Col_Keyword es 'hangzhou' y Col_Long es menor que 4.

private static void knnVectorQuery(SyncClient client) {
    SearchQuery searchQuery = new SearchQuery();
    KnnVectorQuery query = new KnnVectorQuery();
    query.setFieldName("Col_Vector");
    query.setTopK(10); // Return the top K nearest neighbors.
    query.setMinScore(0.1f); // Return only rows with a score greater than 0.1.
    query.setFloat32QueryVector(new float[]{0.1f, 0.2f, 0.3f, 0.4f});
    // The nearest neighbors must also satisfy the conditions: Col_Keyword = 'hangzhou' AND Col_Long < 4.
    query.setFilter(QueryBuilders.bool()
            .must(QueryBuilders.term("Col_Keyword", "hangzhou"))
            .must(QueryBuilders.range("Col_Long").lessThan(4))
    );
    searchQuery.setQuery(query);
    searchQuery.setLimit(10);
    // Sort the results by score.
    searchQuery.setSort(new Sort(Collections.singletonList(new ScoreSort())));
    SearchRequest searchRequest = new SearchRequest("<TABLE_NAME>", "<SEARCH_INDEX_NAME>", searchQuery);
    SearchRequest.ColumnsToGet columnsToGet = new SearchRequest.ColumnsToGet();
    columnsToGet.setColumns(Arrays.asList("Col_Keyword", "Col_Long"));
    searchRequest.setColumnsToGet(columnsToGet);
    // Call the search operation.
    SearchResponse resp = client.search(searchRequest);
    for (SearchHit hit : resp.getSearchHits()) {
        // Print the score.
        System.out.println(hit.getScore());
        // Print the row data.
        System.out.println(hit.getRow());
    }
}

Preguntas frecuentes

How do I optimize the performance of a KNN vector query in Tablestore?

Documentos relacionados