In this tutorial, you prepare an Alibaba Cloud Elasticsearch Agent Engine Edition instance and connect to it. All use cases share this same procedure. After you connect, you can use vector search, Collection and Slice data management, and other capabilities based on your business requirements.
Prepare an instance
Prerequisites
Alibaba Cloud Elasticsearch is activated.
You have planned the virtual private cloud (VPC), vSwitch, access whitelist, and client network for the instance.
The account that you use has the required permissions. For example, when you use a Collection, management operations typically require
manage, data reads requireread, and data writes requirewrite. For more information, see Collection permissions.
Create an instance
When you create an instance, set Elasticsearch Version to Agent Engine Edition. For a production environment, configure at least two query nodes so that queries remain available if a single query node fails. For more information about parameter settings, see Create an Alibaba Cloud Elasticsearch cluster.
Determine the number and specifications of nodes based on write throughput, query concurrency, vector index building, the active dataset, and cache requirements. Persistent data uses object storage with the pay-as-you-go billing method. You do not need to provision storage capacity in advance or scale storage on your own.
Connect to the instance
After you create an Agent Engine Edition instance, you can access it by using Kibana Dev Tools, an Elasticsearch-compatible client, or any HTTP client. Copy the connection parameters from the instance details page. For more information, see Connect to a cluster.
The access domain names of Agent Engine Edition vary based on the network type. A domain name determines only the node role that first receives a request. It does not restrict the request type. The cluster forwards each request to the node role that processes it.
Network type | Domain name | Entry node | Request processing |
VPC | The default Elasticsearch VPC domain name displayed in the console | Query node | Supports read and write requests. Write requests are forwarded to index nodes for processing. |
VPC |
| Index node | Supports read and write requests. Query requests are forwarded to query nodes for processing. |
Internet | The default Elasticsearch public domain name displayed in the console | Query node | Only this domain name is available over the Internet. It supports read and write requests. Write requests are forwarded to index nodes for processing. |
In a production environment, use the default VPC domain name for query requests and the index-node VPC domain name for write requests. This separation reduces network bandwidth usage on query nodes and is especially important for bulk writes, queries that return large results, and high-concurrency scenarios. When you access an instance over the Internet, use the default public domain name for both read and write requests. For example, if the instance ID is es-cn-xxx, the index-node VPC domain name is es-cn-xxx-index.elasticsearch.aliyuncs.com.
Instances use HTTP by default. You must enable HTTPS before you access an instance over the Internet or transmit business credentials. The cURL example in this section uses HTTPS. Use the HTTP endpoint provided in the console only when you verify connectivity in a controlled VPC environment.
Run the following request in Kibana Dev Tools to verify the connection:
GET /The version.number in the response is the Elasticsearch engine version number. It differs from the product version number displayed in the console. To verify the connection with cURL instead, replace <elasticsearch-endpoint> with the endpoint that you copied from the instance details page and <username> with your username. After you run the command, enter the password at the prompt to prevent the password from being written to the command history:
curl --user '<username>' 'https://<elasticsearch-endpoint>/'Select a client
Agent Engine Edition corresponds to engine version 9.99.0. For an existing instance, you can run GET / to check the engine version.
As a best practice, use a client whose minor version matches the minor engine version, which is currently 9.5.x. Within the same major version, clients whose minor version is not later than the minor engine version (9.0 to 9.5) can call the service as expected. Clients whose minor version is later than the minor engine version are not guaranteed to be compatible. The APIs that you can call are always determined by the server-side engine version. Upgrading a client does not provide features, APIs, or request parameters that require a later server-side engine version. For more information, see Elasticsearch client compatibility.
Custom plugin compatibility
When you package or upload a custom plugin, use a plugin package that is built and verified for Agent Engine Edition. In the plugin descriptor file plugin-descriptor.properties, elasticsearch.version=9.99.0 is a plugin compatibility identifier reserved for Agent Engine Edition. When you declare this value, nodes skip the engine version check and load the plugin. The value does not verify binary or API compatibility between the plugin and the engine, and it is not the engine version used as a compile-time dependency. Changing only this field does not guarantee that a plugin of any version works. You must still rebuild and test the plugin for Agent Engine Edition.
Next steps
To run your first vector search, see Vector search example for a standard index.
To organize data by tenant, knowledge base, or code repository, see Vector fields and KNN.
To learn how index nodes, query nodes, and the cache work together, see Stateless architecture and resource planning.