OpenSearch:OSS + API data source

Activate OSS

Activate OSS in the same region as your OpenSearch instance.

Create a bucket

1. Go to OSS Management Console

2. After the bucket is created, add an OpenSearch tag: Go to Bucket Settings > Bucket Tagging > Create Tag.

   

Prepare your data files

Files must meet these requirements before upload:

{"field_double": ["100.0", "221.123", "500.3333333"], "field_int32": ["100", "200", "300"], "title": "Huawei Mate 9 Kirin 960 chip Leica dual camera", "color": "Red", "empty_int32": "", "price": "3599", "CMD": "add", "nid": "1", "gather_cn_str": "", "desc": ["str1", "str2", "str3"], "brand": "Huawei", "size": "5.9","__subdocs__":[{"sub_pk":"100","sub_field1":"200","sub_field2":["100","200","300"]},{"sub_pk":"200","sub_field1":"200","sub_field2":["100","200","300"]}]}
{"field_double": ["100.0", "221.123", "500.3333333", "100.0", "221.123", "500.3333333"], "field_int32": ["100", "200", "300", "100", "200", "300"], "title": "Huawei/Huawei P10 Plus full network phone", "color": "Blue", "empty_int32": "", "price": "4388", "CMD": "add", "nid": "2", "gather_cn_str": "colorBlue", "desc": ["str1", "str2", "str3", "str1", "str2", "str3"], "brand": "Huawei", "size": "5.5","__subdocs__":[{"sub_pk":"100","sub_field1":"200","sub_field2":["100","200","300"]},{"sub_pk":"200","sub_field1":"200","sub_field2":["100","200","300"]}]}

Upload files to the bucket

Place your data files in a folder inside the bucket — not in the root directory. The bucket structure should look like this:

<your-bucket-name>/
  └── <your-data-folder>/
        ├── data_file_1.json
        ├── data_file_2.json
        └── ...

To upload:

1. In the OSS Management Console, open your bucket.

2. In the left navigation pane, go to Object Management > Objects.

3. Click Upload Object, select your files, and confirm.

Set up basic table information

1. In the Instance List, find your Vector Search Edition instance and click Manage in the Actions column.

2. In the left navigation pane, go to Table Management > Add Table.

3. Fill in the basic table information and click Next.

   Field	Description
   Table Name	Custom name for this table
   Number of Data Shards	Positive integer, maximum 256. More shards improve full build speed and single-query performance.
   Number of Data Update Resources	Resources used for incremental data updates. Each index includes two free 4-core 8 GB update resources by default. Additional resources are billed. See Vector Search Edition billing.
   Scenario Template	Choose one: General Template, Vector: Image Search Template, or Vector: Text Semantic Search Template

   

Configure data synchronization

1. For Full Data Source, select Object Storage Service (OSS) + API.

2. Fill in the OSS connection details and click Data Source Verification.

   Field	Description
   OSS Path	Path to the folder containing your data files. Must start with /. Cannot contain ?, =, or &. Files must be in a folder — the root directory is not supported.
   OSS Bucket	Name of the OSS bucket
   Data Format	Select HA3 or JSON to match your uploaded files

   

3. After verification passes, click Next.

   If verification fails, check that the OSS path points to a folder (not the root), the bucket name is correct, the data format matches your files, and OSS is in the same region as your OpenSearch instance.

Configure fields

Vector Search Edition pre-populates fields based on your selected scenario template and imports field definitions from the data source.

1. Review the preset fields. For the Image Search Template, the default fields are:

   Field	Description
   id	Primary key
   source_image	Source image
   namespace	Namespace
   source_image_vector	Source image vector

2. Configure field types and properties:

   • Primary key (required): Set Type to an integer type or STRING, then select the Primary Key option.

   • Vector field (required): Set Type to FLOAT and select the Vector Field checkbox. Vector fields are multi-value FLOAT by default, with comma as the delimiter. Enter a custom delimiter if needed.

   • Default values: When a field is missing or empty in the data, the system fills in a default — 0 for numeric types, an empty string for STRING types. Customize defaults as needed.

3. For fields that require pre-processing (such as source_image), click Configure in the Data Preprocessing column. In the pre-processing configuration:

   • Data Source: Select OSS Object Storage to import images directly from OSS (provide the OSS path), or Base64 Encoding to supply encoded image data via API.

   • Pre-processing Template: Select the template that matches your data type. For images, the available templates are:

     • Image Vectorization

     • OCR Image Text Recognition

     • OCR Image Text Recognition + Image Vectorization

   • Service List: After selecting a template, review the models used. Choose from:

     • Built-in Models: Free to use, with a smaller selection of model types.

   

4. Click Next.

Configure index schema

1. Set the included fields and index parameters, then click Next.

   Parameter	Description
   Included Fields	The primary key and vector field are required. The namespace field is optional.
   Vector Dimension	Dimension count of your vector embeddings
   Real-time Indexing	Enable or disable real-time index updates
   Distance Type	The distance metric for vector similarity search
   Vector Index Algorithm	The algorithm used to build the vector index

   

2. For advanced index parameters, use the defaults or adjust them based on your requirements. See General vector index configuration.

Confirm and verify

1. On the Confirm Creation page, review your settings and click Confirm.

2. Return to the Instance List. The instance status changes to Normal within approximately 2 minutes.

3. When the status is Normal, use Actions > Query Test to run test queries and verify the index is working.