alicloud-ai-search-opensearch

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Category: provider

分类：服务提供商

OpenSearch Vector Search Edition

OpenSearch向量搜索版

Use the ha3engine SDK to push documents and execute HA/SQL searches. This skill focuses on API/SDK usage only (no console steps).

使用ha3engine SDK推送文档并执行HA/SQL搜索。本技能仅聚焦于API/SDK的使用（不含控制台操作步骤）。

Prerequisites

前提条件

Install SDK (recommended in a venv to avoid PEP 668 limits):

bash

python3 -m venv .venv
. .venv/bin/activate
python -m pip install alibabacloud-ha3engine

Provide connection config via environment variables:

```
OPENSEARCH_ENDPOINT
```
(API domain)
```
OPENSEARCH_INSTANCE_ID
```
```
OPENSEARCH_USERNAME
```
```
OPENSEARCH_PASSWORD
```
```
OPENSEARCH_DATASOURCE
```
(data source name)
```
OPENSEARCH_PK_FIELD
```
(primary key field name)

安装SDK（推荐在虚拟环境venv中安装，以避免PEP 668限制）：

bash

python3 -m venv .venv
. .venv/bin/activate
python -m pip install alibabacloud-ha3engine

通过环境变量提供连接配置：

```
OPENSEARCH_ENDPOINT
```
（API域名）
```
OPENSEARCH_INSTANCE_ID
```
```
OPENSEARCH_USERNAME
```
```
OPENSEARCH_PASSWORD
```
```
OPENSEARCH_DATASOURCE
```
（数据源名称）
```
OPENSEARCH_PK_FIELD
```
（主键字段名称）

Quickstart (push + search)

快速入门（推送+搜索）

python

import os
from alibabacloud_ha3engine import models, client
from Tea.exceptions import TeaException, RetryError

cfg = models.Config(
    endpoint=os.getenv("OPENSEARCH_ENDPOINT"),
    instance_id=os.getenv("OPENSEARCH_INSTANCE_ID"),
    protocol="http",
    access_user_name=os.getenv("OPENSEARCH_USERNAME"),
    access_pass_word=os.getenv("OPENSEARCH_PASSWORD"),
)
ha3 = client.Client(cfg)

def push_docs():
    data_source = os.getenv("OPENSEARCH_DATASOURCE")
    pk_field = os.getenv("OPENSEARCH_PK_FIELD", "id")

    documents = [
        {"fields": {"id": 1, "title": "hello", "content": "world"}, "cmd": "add"},
        {"fields": {"id": 2, "title": "faq", "content": "vector search"}, "cmd": "add"},
    ]
    req = models.PushDocumentsRequestModel({}, documents)
    return ha3.push_documents(data_source, pk_field, req)


def search_ha():
    # HA query example. Replace cluster/table names as needed.
    query_str = (
        "config=hit:5,format:json,qrs_chain:search"
        "&&query=title:hello"
        "&&cluster=general"
    )
    ha_query = models.SearchQuery(query=query_str)
    req = models.SearchRequestModel({}, ha_query)
    return ha3.search(req)

try:
    print(push_docs().body)
    print(search_ha())
except (TeaException, RetryError) as e:
    print(e)

python

import os
from alibabacloud_ha3engine import models, client
from Tea.exceptions import TeaException, RetryError

cfg = models.Config(
    endpoint=os.getenv("OPENSEARCH_ENDPOINT"),
    instance_id=os.getenv("OPENSEARCH_INSTANCE_ID"),
    protocol="http",
    access_user_name=os.getenv("OPENSEARCH_USERNAME"),
    access_pass_word=os.getenv("OPENSEARCH_PASSWORD"),
)
ha3 = client.Client(cfg)

def push_docs():
    data_source = os.getenv("OPENSEARCH_DATASOURCE")
    pk_field = os.getenv("OPENSEARCH_PK_FIELD", "id")

    documents = [
        {"fields": {"id": 1, "title": "hello", "content": "world"}, "cmd": "add"},
        {"fields": {"id": 2, "title": "faq", "content": "vector search"}, "cmd": "add"},
    ]
    req = models.PushDocumentsRequestModel({}, documents)
    return ha3.push_documents(data_source, pk_field, req)


def search_ha():
    # HA query example. Replace cluster/table names as needed.
    query_str = (
        "config=hit:5,format:json,qrs_chain:search"
        "&&query=title:hello"
        "&&cluster=general"
    )
    ha_query = models.SearchQuery(query=query_str)
    req = models.SearchRequestModel({}, ha_query)
    return ha3.search(req)

try:
    print(push_docs().body)
    print(search_ha())
except (TeaException, RetryError) as e:
    print(e)

Script quickstart

脚本快速入门

bash

python skills/ai/search/alicloud-ai-search-opensearch/scripts/quickstart.py

Environment variables:

```
OPENSEARCH_ENDPOINT
```
```
OPENSEARCH_INSTANCE_ID
```
```
OPENSEARCH_USERNAME
```
```
OPENSEARCH_PASSWORD
```
```
OPENSEARCH_DATASOURCE
```
```
OPENSEARCH_PK_FIELD
```
(optional, default
```
id
```
)
```
OPENSEARCH_CLUSTER
```
(optional, default
```
general
```
)

Optional args:

--cluster

--hit

--query

bash

python skills/ai/search/alicloud-ai-search-opensearch/scripts/quickstart.py

环境变量：

```
OPENSEARCH_ENDPOINT
```
```
OPENSEARCH_INSTANCE_ID
```
```
OPENSEARCH_USERNAME
```
```
OPENSEARCH_PASSWORD
```
```
OPENSEARCH_DATASOURCE
```
```
OPENSEARCH_PK_FIELD
```
（可选，默认值为
```
id
```
）
```
OPENSEARCH_CLUSTER
```
（可选，默认值为
```
general
```
）

可选参数：

--cluster

--hit

--query

。

SQL-style search

SQL风格搜索

python

from alibabacloud_ha3engine import models

sql = "select * from <indexTableName>&&kvpair=trace:INFO;formatType:json"
sql_query = models.SearchQuery(sql=sql)
req = models.SearchRequestModel({}, sql_query)
resp = ha3.search(req)
print(resp)

python

from alibabacloud_ha3engine import models

sql = "select * from <indexTableName>&&kvpair=trace:INFO;formatType:json"
sql_query = models.SearchQuery(sql=sql)
req = models.SearchRequestModel({}, sql_query)
resp = ha3.search(req)
print(resp)

Notes for Claude Code/Codex

针对Claude Code/Codex的注意事项

Use
```
push_documents
```
for add/delete updates.
Large query strings (>30KB) should use the RESTful search API.
HA queries are fast and flexible for vector + keyword retrieval; SQL is helpful for structured data.

使用
```
push_documents
```
进行新增/删除更新。
超过30KB的大型查询字符串应使用RESTful搜索API。
HA查询在向量+关键词检索中快速且灵活；SQL则对结构化数据处理有帮助。

Error handling

错误处理

Auth errors: verify username/password and instance access.
4xx on push: check schema fields and
```
pk_field
```
alignment.
5xx: retry with backoff.

认证错误：验证用户名/密码和实例访问权限。
推送时出现4xx错误：检查schema字段与
```
pk_field
```
是否匹配。
5xx错误：通过退避策略重试。

References

参考资料

SDK package:
```
alibabacloud-ha3engine
```
Demos: data push and HA/SQL search demos in OpenSearch docs
Source list:
```
references/sources.md
```

SDK包：
```
alibabacloud-ha3engine
```
示例：OpenSearch文档中的数据推送及HA/SQL搜索示例
来源列表：
```
references/sources.md
```