Quick start for General Edition
Purchase an instance
For information about how to purchase an instance, see Purchase an OpenSearch Vector Search Edition instance.
Configure an instance
On the details page of a newly purchased instance, the instance status is "Pending Configuration". Go to the instance details page and configure the instance in the following order: Basic Table Information > Data Synchronization > Field Configuration > Index Schema > Confirm Creation. Then wait until the index is rebuilt. After that, you can perform searches as normal.
In the instance list, find the target instance and click Configure in the Actions column to go to the configuration page.
1. Basic table information
In Table Management, click "Add Table", enter a Table Name, set the Number of Data Shards and the Number of Data Update Resources, select the required Scenario Template, and then click Next.
Configuration description:
Table Name: You can specify a custom name.
Number of Data Shards: Enter a positive integer that does not exceed 256. Shards are used to improve the speed of full data builds and the performance of individual queries. (For some existing instances, all index tables must still have the same number of shards, or at least one index table must have 1 shard and all other index tables must have the same number of shards.)
Number of Data Update Resources: the number of resources used for data updates. By default, each index is provided with 2 free update resources, each with 4 cores and 8 GB of memory. Resources that exceed the free quota incur fees. For more information, see Billing overview of OpenSearch Vector Search Edition
Scenario Template: OpenSearch Vector Search Edition provides 3 built-in templates: General, Vector - Image Search, and Vector - Text Semantic Search.
Description of each scenario template:
General template: an empty template with no preset fields or indexes.
Vector: Image Search: uses the built-in vectorization model of OpenSearch to convert raw image data into dense vectors.
Vector: Text Semantic Search: converts text into dense vectors to implement semantic analysis. You can select Dense Vector Retrieval or Dense & Sparse Vector Hybrid Retrieval.
2. Data synchronization
Select a Full Data Source. Supported data sources include MaxCompute+API, Object Storage Service (OSS)+API, Synchronize vector data from OpenLake-DLF to Alibaba Cloud OpenSearch, and API data source. This topic uses MaxCompute+API as an example. Set AccessKey, AccessKey Secret, Project, Table, and Partition in sequence, and specify whether to enable "Automatic Index Rebuild" as needed. After the settings are complete, click Verify in the Data Source Verification section. You can proceed to the next step only after the verification is successful.
3. Field configuration
OpenSearch presets related fields based on the scenario template that you select, and automatically imports the fields from the full data source (if any) into the field list. You must configure at least two fields: a primary key field and a vector field (the vector field must be set to the multi-value float type). If you need vectors with categories, you can add a category field between the primary key field and the vector field.
Field configuration description:
Required fields: primary key field and vector field. The primary key field must be of the int or string type, and you must select the primary key option for it. The vector field must be of the float type, and you must select the vector field option for it.
By default, the vector field is of the multi-value float type. When you create a table in the console, values are split by commas by default. Custom multi-value delimiters are supported.
To use vector retrieval, fields must be defined in a specific order: the primary key field, the namespace field (optional), and then the vector field.
If a field is missing from the data or is empty, the system automatically fills in a default value. Numeric types default to 0, and the STRING type defaults to an empty string. Custom default values are supported.
4. Index schema
OpenSearch automatically creates indexes for the primary key field and the vector field. The index names are the same as the field names. You only need to configure the vector index in the console:
Index name: embedding
Vector dimension: 128
Distance type: SquaredEuclidean
Vector index algorithm: Qc
Real-time index: true
Configure the Advanced Settings as needed. For more information, see General vector index configuration.
The primary key field and the vector field are required. The namespace field is optional and can be left empty.
You can select only the three fixed fields. Adding fields is not supported.
The system automatically populates the configuration parameters of the vector index. If you have no special requirements, you can click OK to quickly complete the configuration.
Namespace field: If the engine version of the instance is vector service 1.0.2 or earlier, the namespace tag field does not support the string type. If the engine version of the instance is vector service 1.0.2 or later, this limit does not apply.
5. Confirm creation
After the index configuration is complete, click Confirm Creation.
After you confirm, the system automatically builds the index. The creation is expected to take 2 minutes. After the build is complete, the index is automatically enabled in the current instance.
After you click Confirm Creation, the new table appears in the Table Management list with the status Creating. Wait until the creation is complete.
6. Change history
In Instance Management > Change History > Data Source Changes, you can view all FSMs for table creation, index addition, and full data builds. After all of them are complete, the engine is set up and you can start adding data and testing queries:
When expanded, the Add Table operation contains two change processes:
Subscribe to/Unsubscribe from Index Table: The change nodes are, in sequence: parameter check, subscription status modification, submission to the online cluster, and waiting for the status to take effect.
Manually Trigger Full Build: The change nodes are, in sequence: parameter check, trigger, and data source scan.
A green check mark on a node indicates that the step is complete.
7. Query test
In the left-side navigation pane, choose Vector Management > Query Test to run queries, Query tests support both form mode and developer mode.
7.1 Form mode
Select Form Mode > Table Name in sequence, set Query Type to Vector, enter the query parameters in the Vector box, and then click Search. The results are displayed in the Search Results section.
In the form, you must also select an Index Name (for example, embedding) and set TopK (for example, 10). You can specify Filter Conditions, Namespace, and Result Sort Order as needed. The search results are displayed in a table that includes columns such as distance score, primary key, vector value, attributes, and namespace.
7.2 Developer mode
Select Developer Mode > Table Name in sequence, enter the query parameters in the Search box below, and then click Search. The query results are displayed in the Results section on the right.
The query parameters also include indexName, which specifies the name of the index to query. Example value: "embedding".
vector: the vector to query
topK: the number of top K results to return
includeVector: specifies whether to return the vector information in the documents
For the detailed query syntax, see the syntax description below.
Syntax description
Use vector retrieval in SDKs
Query data (perform vector and primary key queries by using SDKs)
Update data (add and delete records by using SDKs)