Demostración de inserción - OpenSearch - Centro de documentación de Alibaba Cloud

Esta página demuestra cómo insertar documentos en una aplicación de OpenSearch mediante el SDK de OpenSearch para Java V3.1. El ejemplo abarca las operaciones ADD, UPDATE y DELETE en un solo lote de inserción, seguido de una consulta de búsqueda para comprobar los resultados.

Requisitos previos

Antes de empezar, asegúrese de contar con lo siguiente:

Una aplicación de OpenSearch con al menos una tabla configurada.
El AccessKey ID y el AccessKey secret de un usuario de Resource Access Management (RAM) que tenga los permisos necesarios otorgados al rol AliyunServiceRoleForOpenSearch. Para obtener más información sobre el rol, consulte AliyunServiceRoleForOpenSearch. Para más detalles sobre los permisos, consulte Reglas de autorización de acceso.
El SDK de OpenSearch para Java V3.1 agregado a su proyecto.

Importante

Utilice el par de AccessKey de un usuario de RAM en lugar del par de AccessKey de su cuenta de Alibaba Cloud. El par de AccessKey a nivel de cuenta otorga acceso a todas las operaciones de la API y representa un mayor riesgo de seguridad. Para crear un usuario de RAM, consulte Crear un usuario de RAM. Para crear un par de AccessKey, consulte Crear un par de AccessKey.

Configurar las credenciales

Almacene su par de AccessKey como variables de entorno. Esto evita que las credenciales queden expuestas en su código fuente.

Linux y macOS

export ALIBABA_CLOUD_ACCESS_KEY_ID=<access_key_id>
export ALIBABA_CLOUD_ACCESS_KEY_SECRET=<access_key_secret>

Reemplace <access_key_id> y <access_key_secret> con el AccessKey ID y el AccessKey secret de su usuario de RAM.

Windows

Cree un archivo de variables de entorno y agregue ALIBABA_CLOUD_ACCESS_KEY_ID y ALIBABA_CLOUD_ACCESS_KEY_SECRET al archivo, asignando a cada uno el valor correspondiente.
Reinicie Windows para que los cambios surtan efecto.

Funcionamiento

El flujo de trabajo de inserción consta de tres pasos:

Construya cada documento como un objeto Map que contenga los valores de los campos y, a continuación, envuélvalo en un JSONObject con un comando (ADD o DELETE).
Agrupe todas las entradas de JSONObject en un JSONArray y luego invoque documentClient.push() para enviar el lote a la aplicación.
Después de la inserción, ejecute una consulta de búsqueda mediante SearcherClient para comprobar que los documentos aparecen en los resultados.

En una sola llamada de inserción solo puede insertar campos que pertenezcan a la misma tabla. No se admite la inserción de campos de diferentes tablas en una única llamada.

Restricciones y formato de datos

Los conjuntos de datos deben tener un formato válido. Para descargar un archivo de muestra como plantilla, inicie sesión en la consola de OpenSearch, vaya a la página Instance Management, busque su aplicación y elija More > Upload File en la columna Actions.
Construya los documentos directamente con objetos JSONObject y JSONArray, como se muestra en el siguiente ejemplo.
Si la cantidad de documentos en una sola inserción supera el límite, la operación fallará con un error.
Las aplicaciones estándar admiten el comando ADD tanto para agregar como para reemplazar documentos por completo. El comando UPDATE (actualización parcial de campos) solo es compatible con aplicaciones avanzadas.

Insertar y consultar documentos

El siguiente ejemplo inserta cuatro documentos en una sola llamada: agrega dos documentos (doc1, doc2), actualiza uno (doc2 se reemplaza por doc3) y elimina otro (doc1). Posteriormente, realiza una consulta por clave principal para verificar los resultados.

package com.aliyun.opensearch;

import com.aliyun.opensearch.sdk.dependencies.com.google.common.collect.Lists;
import com.aliyun.opensearch.sdk.dependencies.com.google.common.collect.Maps;
import com.aliyun.opensearch.sdk.dependencies.org.json.JSONArray;
import com.aliyun.opensearch.sdk.dependencies.org.json.JSONObject;
import com.aliyun.opensearch.sdk.generated.OpenSearch;
import com.aliyun.opensearch.sdk.generated.commons.OpenSearchClientException;
import com.aliyun.opensearch.sdk.generated.commons.OpenSearchException;
import com.aliyun.opensearch.sdk.generated.commons.OpenSearchResult;
import com.aliyun.opensearch.sdk.generated.document.Command;
import com.aliyun.opensearch.sdk.generated.document.DocumentConstants;
import com.aliyun.opensearch.sdk.generated.search.*;
import com.aliyun.opensearch.sdk.generated.search.general.SearchResult;

import java.io.UnsupportedEncodingException;
import java.nio.charset.Charset;
import java.util.Map;
import java.util.Random;

public class testPushSearch2 {

    private String appName = "Name of the OpenSearch application that you want to manage"; // (1)
    private String tableName = "Name of the table to which data is to be uploaded";          // (2)
    private String host = "Endpoint of the OpenSearch API in your region";                  // (3)

    public static void main(String[] args) {

        // Read credentials from environment variables                                       // (4)
        String accesskey = System.getenv("ALIBABA_CLOUD_ACCESS_KEY_ID");
        String secret = System.getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET");

        System.out.println(String.format("file.encoding: %s", System.getProperty("file.encoding")));
        System.out.println(String.format("defaultCharset: %s", Charset.defaultCharset().name()));

        // ---- Build documents ----

        // Generate random primary key values for doc1 and doc2                              // (5)
        Random rand = new Random();
        int value1 = rand.nextInt(Integer.MAX_VALUE);
        int value2 = rand.nextInt(Integer.MAX_VALUE);

        // doc1: ADD — adds a new document                                                   // (6)
        Map<String, Object> doc1 = Maps.newLinkedHashMap();
        doc1.put("id", value1);

        String title_string = "Upload doc1 in push mode";// UTF-8.
        byte[] bytes;
        try {
            bytes = title_string.getBytes("utf-8");
            String utf8_string = new String(bytes, "utf-8");
            doc1.put("name", utf8_string);
        } catch (UnsupportedEncodingException e) {
            e.printStackTrace();
        }

        doc1.put("phone", "137****1111");

        int[] int_arr = {11,11};
        doc1.put("int_arr", int_arr);

        String[] literal_arr1 = {"Upload doc1 in push mode","Test uploading doc1 in push mode"};
        doc1.put("literal_arr", literal_arr1);

        float[] float_arr = {(float)1.1,(float)1.1};
        doc1.put("float_arr", float_arr);

        doc1.put("cate_id", 1);

        // Standard applications use ADD for both adding and fully replacing documents.      // (7)
        // UPDATE (partial field update) is not supported for standard applications.
        JSONObject json1 = new JSONObject();
        json1.put(DocumentConstants.DOC_KEY_CMD, Command.ADD.toString());
        json1.put(DocumentConstants.DOC_KEY_FIELDS, doc1);

        // doc2: ADD — adds a new document                                                   // (8)
        Map<String, Object> doc2 = Maps.newLinkedHashMap();
        doc2.put("id", value2);

        String title_string2 = "Upload doc2 in push mode";// UTF-8.
        byte[] bytes2;
        try {
            bytes2 = title_string2.getBytes("utf-8");
            String utf8_string2 = new String(bytes2, "utf-8");
            doc2.put("name", utf8_string2);
        } catch (UnsupportedEncodingException e) {
            e.printStackTrace();
        }

        doc2.put("phone", "137****2222");

        int[] int_arr2 = {22,22};
        doc2.put("int_arr", int_arr2);

        String[] literal_arr2 = {"Upload doc2 in push mode","Test uploading doc2 in push mode"};
        doc2.put("literal_arr", literal_arr2);

        float[] float_arr2 = {(float)2.2,(float)2.2};
        doc2.put("float_arr", float_arr2);

        doc2.put("cate_id", 1);

        JSONObject json2 = new JSONObject();
        json2.put(DocumentConstants.DOC_KEY_CMD, Command.ADD.toString());
        json2.put(DocumentConstants.DOC_KEY_FIELDS, doc2);

        // doc3: ADD with doc2's primary key — replaces doc2 with doc3's field values        // (9)
        Map<String, Object> doc3 = Maps.newLinkedHashMap();
        doc3.put("id", value2);   // same primary key as doc2

        String title_string3 = "Update doc2 to doc3 in push mode";// UTF-8.
        byte[] bytes3;
        try {
            bytes3 = title_string3.getBytes("utf-8");
            String utf8_string3 = new String(bytes3, "utf-8");
            doc3.put("name", utf8_string3);
        } catch (UnsupportedEncodingException e) {
            e.printStackTrace();
        }

        doc3.put("phone", "137****3333");

        int[] int_arr3 = {33,33};
        doc3.put("int_arr", int_arr3);

        String[] literal_arr3 = {"Update doc2 to doc3 in push mode","Update doc2 to doc3 in push mode"};
        doc3.put("literal_arr", literal_arr3);

        float[] float_arr3 = {(float)3.3,(float)3.3};
        doc3.put("float_arr", float_arr3);

        doc3.put("cate_id", 1);

        JSONObject json3 = new JSONObject();
        json3.put(DocumentConstants.DOC_KEY_CMD, Command.ADD.toString());
        json3.put(DocumentConstants.DOC_KEY_FIELDS, doc3);

        // doc4: DELETE — removes doc1 by primary key only                                   // (10)
        Map<String, Object> doc4 = Maps.newLinkedHashMap();
        doc4.put("id", value1);   // only the primary key is needed for deletion

        JSONObject json4 = new JSONObject();
        json4.put(DocumentConstants.DOC_KEY_CMD, Command.DELETE.toString());
        json4.put(DocumentConstants.DOC_KEY_FIELDS, doc4);

        // ---- Push documents ----

        JSONArray docsJsonArr = new JSONArray();
        docsJsonArr.put(json1);  // add doc1
        docsJsonArr.put(json2);  // add doc2
        docsJsonArr.put(json3);  // replace doc2 with doc3
        docsJsonArr.put(json4);  // delete doc1
        String docsJson = docsJsonArr.toString();

        // Initialize the client                                                             // (11)
        OpenSearch openSearch = new OpenSearch(accesskey, secret, host);
        OpenSearchClient serviceClient = new OpenSearchClient(openSearch);
        DocumentClient documentClient = new DocumentClient(serviceClient);

        try {
            OpenSearchResult osr = documentClient.push(docsJson, appName, tableName);       // (12)

            // A "true" result means the push request was accepted without errors.
            // Check the OpenSearch console error logs for any post-push processing errors
            // (such as field type conversion failures).
            if (osr.getResult().equalsIgnoreCase("true")) {
                System.out.println("Push accepted. Request ID: " + osr.getTraceInfo().getRequestId());
            } else {
                System.out.println("Push failed: " + osr.getTraceInfo());
            }

        } catch (OpenSearchException e) {
            e.printStackTrace();
        } catch (OpenSearchClientException e) {
            e.printStackTrace();
        }

        // ---- Query to verify ----

        // Wait 1 second for indexing to complete before querying                            // (13)
        try {
            Thread.sleep(1000);
        } catch (InterruptedException e) {
            e.printStackTrace();
        }

        SearcherClient searcherClient = new SearcherClient(serviceClient);

        // Configure paging and return format                                                // (14)
        Config config = new Config(Lists.newArrayList(appName));
        config.setStart(0);
        config.setHits(30);
        config.setSearchFormat(SearchFormat.JSON);  // supported formats: XML, JSON (FULLJSON not supported)

        config.setFetchFields(Lists.newArrayList("id", "name", "phone", "int_arr", "literal_arr", "float_arr", "cate_id"));

        SearchParams searchParams = new SearchParams(config);

        // Query by primary key — match either value1 or value2                              // (15)
        // To query on multiple index fields, combine them in one setQuery call.
        // Each additional setQuery call overwrites the previous one.
        searchParams.setQuery("id:'" + value1 + "'|'" + value2 + "'");

        searchParams.setFilter("cate_id<=3");

        // Sort by id descending; break ties by RANK ascending                              // (16)
        Sort sorter = new Sort();
        sorter.addToSortFields(new SortField("id", Order.DECREASE));
        sorter.addToSortFields(new SortField("RANK", Order.INCREASE));
        searchParams.setSort(sorter);

        try {
            SearchResult searchResult = searcherClient.execute(searchParams);
            String result = searchResult.getResult();
            JSONObject obj = new JSONObject(result);
            System.out.println(obj.toString());

        } catch (OpenSearchException e) {
            e.printStackTrace();
        } catch (OpenSearchClientException e) {
            e.printStackTrace();
        }
    }
}

Notas explicativas:

#	Descripción
(1)	Establezca `appName` con el nombre de su aplicación de OpenSearch.
(2)	Establezca `tableName` con el nombre de la tabla de la aplicación donde desea insertar los datos.
(3)	Establezca `host` con el endpoint de la API de OpenSearch correspondiente a su región.
(4)	Las credenciales se leen de las variables de entorno configuradas en Configurar las credenciales.
(5)	En esta demostración se utilizan enteros aleatorios como valores de clave principal. En un entorno de producción, utilice los ID reales de sus documentos.
(6)	Cada documento se construye como un objeto `Map<String, Object>` y luego se envuelve en un `JSONObject` junto con `DOC_KEY_CMD` y `DOC_KEY_FIELDS`.
(7)	`Command.ADD` agrega un nuevo documento si la clave principal no existe, o reemplaza por completo el documento existente si ya existe.
(8)	Se agrega un segundo documento (`doc2`) con su propia clave principal única (`value2`).
(9)	`doc3` utiliza la misma clave principal que `doc2` (`value2`), por lo que el comando `ADD` reemplaza totalmente a `doc2` con los valores de campo de `doc3`.
(10)	`Command.DELETE` elimina un documento por su clave principal. Solo se requiere el campo de clave principal en la carga útil.
(11)	Cree un objeto `OpenSearch` con sus credenciales y endpoint, y utilícelo para inicializar `OpenSearchClient` y `DocumentClient`.
(12)	`documentClient.push()` envía todo el lote en una sola solicitud. Un resultado `"true"` indica que la solicitud se aceptó; revise los registros de errores en la consola para detectar problemas de procesamiento posteriores a la inserción.
(13)	La indexación es asíncrona. Una pausa de 1 segundo permite que el motor indexe los documentos antes de ejecutar la consulta de verificación. En producción, implemente una estrategia de reintento o sondeo en su lugar.
(14)	`Config` define los parámetros de paginación (`start`, `hits`) y el formato de respuesta. `fetchFields` controla qué campos se devuelven.
(15)	La consulta usa el campo de índice `id` para coincidir con cualquiera de las claves principales. Es necesario combinar varios campos en una sola llamada a `setQuery`, ya que cada llamada subsiguiente sobrescribe la anterior.
(16)	Los resultados se ordenan por `id` en orden descendente. Cuando varios documentos comparten el mismo valor de `id`, se ordenan por puntuación de relevancia (`RANK`) en orden ascendente.