This tutorial walks you through setting up an OpenSearch Retrieval Engine Edition instance for the first time — from purchase to running your first search query. The steps here use a MaxCompute data source.
OpenSearch Retrieval Engine Edition supports only the pay-as-you-go billing method. Review your node configurations carefully before purchasing, as the cluster name cannot be changed after creation.
Prerequisites
Before you begin, make sure you have:
An Alibaba Cloud account with real-name verification complete
An AccessKey pair — required to create and use an OpenSearch application. Log in to the console for the first time and follow the prompt to create one. To use a RAM user instead, grant that user the AliyunSearchEngineFullAccess or AliyunSearchEngineReadOnlyAccess permission using your main account. See RAM authorization
A virtual private cloud (VPC). See What is a VPC?
Key concepts
Two worker types make up a Retrieval Engine Edition cluster:
| Worker type | Role |
|---|---|
| Query Result Searcher (QRS) worker | Handles incoming queries and coordinates results |
| Searcher worker | Stores index data and executes searches |
The numbers and types of workers you select at purchase determine cluster capacity.
Purchase an instance
Log in to the OpenSearch console. In the upper-left corner, switch to OpenSearch Retrieval Engine Edition.
In the left navigation pane, click Instance Management, then click Create Instance.
On the purchase page, set Service Edition to Retrieval Engine Edition and select a region. Configure the following parameters: The total fee updates automatically as you adjust specifications. Click Buy Now when ready.
Parameter Description Query Node Quantity Number of QRS workers Query Node Type Specification of each QRS worker Data Node Quantity Number of Searcher workers Data Node Type Specification of each Searcher worker Free Storage Space of Single Data Node Free quota per Searcher worker; increase in 50 GB increments if needed. Storage beyond the free quota is charged. VPC Must match the VPC of the ECS instance you use to access this OpenSearch instance. A mismatch returns {'errors':{'code':'403','message':'Forbidden'}}.vSwitch Must match the vSwitch of the ECS instance Username / Password Used for query authentication — not your Alibaba Cloud account password On the Confirm Order page, review the configuration and service agreement, then click Activate Now.
After the purchase completes, click Console. Your instance appears on the Instance Management page.
The instance name is set automatically. To rename it, click Manage in the Actions column, click the Modify icon, enter a new name, and click Confirm.
Configure the cluster
The instance starts in Pending Configuration state. An empty cluster is automatically deployed with the worker counts and types you selected. Before the search service is usable, configure a data source, define an index schema, and rebuild the indexes.
Step 1: Add a data source
On the instance details page, in the Configure Data Source step, click Add Data Source. In the panel that appears:
Set the data source type to MaxCompute.
Fill in Project, AccessKey ID, AccessKey Secret, Table, and Partition Key.
Optionally enable Automatic Reindexing if you want indexes to rebuild automatically when the source data changes.
After verification passes, click OK.
Alternatively, use an API data source if you plan to push documents programmatically.
Step 2: Define the index schema
Click Next to move to the index schema step.
Click Add Index Table.
Set the index table parameters:
Parameter Description Index Table A custom name for this table Data Source Select the data source you added in Step 1 Data Shards Set this to match the number of Searcher workers you purchased Configure attribute fields and field data compression:
If you compress attribute fields, modify the index loading method to reduce the performance impact. Go to the instance details page > Deployment Management > click the Searcher worker > Searcher Worker Configurations panel > Online Table Configurations tab.
Setting Default Compressed option Attribute fields Not compressed Select file_compressor to compress Multi-value fields and STRING fields uniq — Single-value fields equal — Configure index fields:
Index fields are not compressed by default. Select file_compressor to compress.
The primary key index cannot be compressed.
If you compress index fields, modify the index loading method using the same path: Deployment Management > Searcher worker > Searcher Worker Configurations > Online Table Configurations.
Click Save Version, enter an optional description, and click Publish.
Step 3: Rebuild the index
Click Next to go to the rebuild step. Configure the rebuild parameters based on your data source type and click Next to start.
Check reindexing progress
After the rebuild starts, monitor progress from two places:
Cluster topology: Go to Deployment Management to see a visual overview of the cluster.
Reindexing status: In the left navigation pane, go to O&M Center > Change History > Data Source Changes tab.
When both the QRS workers and Searcher workers on the instance details page show a normal status, the cluster is ready.
Run a query test
In the left navigation pane, go to Extended Features > Query Test.
The query test page supports both HA3 query clauses and SQL clauses.
For query syntax references, see:
Usage notes
| Item | Detail |
|---|---|
| Billing | OpenSearch Retrieval Engine Edition supports only pay-as-you-go |
| Credentials | The username and password set during purchase can be changed on the instance details page |
| Cluster name | Assigned by the system at purchase and cannot be modified |
| Storage | Storage beyond the free quota per Searcher worker is charged; increase the quota in 50 GB increments |
What's next
Configure a MaxCompute data source — detailed parameter reference
Configure an API data source — push documents via API
Query syntax reference — full HA3 and SQL syntax