# Retrieval

#### 概述

智慧化数据平台（AIP）为应用提供构建端侧智慧化解决方案，提供向量化、知识检索和知识问答的能力。

**起始版本：** 6.0.0(20)

#### 汇总

#### 文件

| 名称 | 描述 |
| --- | --- |
| aip_retrieval.h | 提供知识检索相关的接口。 |
| aip_retrieval_condition.h | 提供与检索条件相关的接口。 |
| aip_retrieval_condition_vector.h | 提供与向量条件相关的接口。 |
| aip_retrieval_query.h | 提供与检索查询相关的接口。 |
| aip_retrieval_record.h | 提供与检索结果相关的接口。 |

#### 类型定义

| 名称 | 描述 |
| --- | --- |
| typedef struct OH_Retrieval_Retriever OH_Retrieval_Retriever | 定义检索器类型，检索器是进行检索的句柄。 |
| typedef struct OH_Retrieval_Config OH_Retrieval_Config | 定义检索器配置。 |
| typedef struct OH_Retrieval_DbConfig OH_Retrieval_DbConfig | 定义一个用于打开数据库存储的数据库配置。 |
| typedef enum Retrieval_Channel_Type Retrieval_Channel_Type | 定义数据索引类型，目前仅包括向量索引数据。 |
| typedef void(* OH_Retrieval_Callback) (void *context, OH_Retrieval_Record *record, int errCode) | 检索结果记录的回调函数。 |
| typedef struct OH_Retrieval_Condition OH_Retrieval_Condition | 定义检索条件，可包含多个子检索条件等。 |
| typedef struct OH_Retrieval_SubCondition OH_Retrieval_SubCondition | 定义子检索条件，可以是向量检索。 |
| typedef struct OH_Retrieval_SubCondition OH_Retrieval_VectorCondition | 定义向量检索条件，包含检索的字段、检索参数、过滤条件等。 |
| typedef struct OH_Retrieval_Query OH_Retrieval_Query | 定义检索词，当前只支持纯文本检索。 |
| typedef struct OH_Retrieval_Record OH_Retrieval_Record | 定义检索结果，包含检索知识库得到的字段和字段取值。 |
| typedef struct OH_Retrieval_RecordItem OH_Retrieval_RecordItem | 定义检索结果中的数据库bucket数组。 |

#### 枚举

| 名称 | 描述 |
| --- | --- |
| Retrieval_Channel_Type { RETRIEVAL_TYPE_VECTOR = 1 } | 定义数据索引类型，目前仅包括向量索引数据。 |

#### 函数

| 名称 | 描述 |
| --- | --- |
| int OH_Retrieval_CreateRetriever (const OH_Retrieval_Config *config, OH_Retrieval_Retriever **retriever) | 获取检索器。 |
| int OH_Retrieval_DestroyRetriever (OH_Retrieval_Retriever *retriever) | 销毁通过OH_Retrieval_CreateRetriever获得的检索器。 |
| OH_Retrieval_Config * OH_Retrieval_CreateConfig () | 获取检索器配置。 |
| int OH_Retrieval_DestroyConfig (OH_Retrieval_Config *config) | 销毁通过OH_Retrieval_CreateConfig获得的检索配置。 |
| OH_Retrieval_DbConfig * OH_Retrieval_CreateDbConfig () | 创建一个配置项以打开数据库。 |
| int OH_Retrieval_DestroyDbConfig (OH_Retrieval_DbConfig *dbConfig) | 销毁OH_Retrieval_CreateDbConfig创建的OH_Retrieval_DbConfig。 |
| int OH_Retrieval_SetDbConfig (OH_Retrieval_DbConfig *dbConfig, OH_Rdb_ConfigV2*rdbConfig) | 设置OH_Retrieval_DbConfig中的数据库配置。 |
| int OH_Retrieval_AddConfig (OH_Retrieval_Config *config, Retrieval_Channel_Type channelType, OH_Retrieval_DbConfig *dbConfig) | 设置OH_Retrieval_Config中的数据库配置。 |
| int OH_Retrieval_Retrieve (const OH_Retrieval_Retriever *retriever, const OH_Retrieval_Query *query, const OH_Retrieval_Condition *condition, void *context, const OH_Retrieval_Callback *callback) | 执行检索。获得检索器句柄后，输入检索查询词，根据检索条件执行检索，得到检索结果。 |
| OH_Retrieval_Condition * OH_Retrieval_CreateCondition () | 创建检索条件，作为检索接口的入参。 |
| int OH_Retrieval_DestroyCondition (OH_Retrieval_Condition *condition) | 销毁通过OH_Retrieval_CreateCondition获得的检索条件。 |
| int OH_Retrieval_DestroySubCondition (OH_Retrieval_SubCondition *condition) | 销毁OH_Retrieval_SubCondition对象。 |
| int OH_Retrieval_AddSubCondition (OH_Retrieval_Condition *condition, OH_Retrieval_SubCondition *subCondition) | 在检索条件中，增加子检索条件。 |
| OH_Retrieval_VectorCondition * OH_Retrieval_CreateVectorCondition () | 创建向量检索条件。 |
| int OH_Retrieval_DestroyVectorCondition (OH_Retrieval_VectorCondition *condition) | 销毁通过OH_Retrieval_CreateVectorCondition获得的检索条件。 |
| int OH_Retrieval_SetVectorRecallLimit (OH_Retrieval_VectorCondition *condition, uint32_t limit) | 在检索条件中，设置向量检索结果数量上限1000。 |
| int OH_Retrieval_SetSimilarityThreshold (OH_Retrieval_VectorCondition *condition, double threshold) | 在检索条件中，设置向量检索的相似度阈值。 |
| OH_Retrieval_Query * OH_Retrieval_CreateQuery () | 创建检索词，作为检索接口的入参。 |
| int OH_Retrieval_DestroyQuery (OH_Retrieval_Query *query) | 销毁通过OH_Retrieval_CreateQuery获得的检索词。 |
| int OH_Retrieval_SetOriginalQuestion (OH_Retrieval_Query *query, const char *question) | 设置OH_Retrieval_Query中的检索词。 |
| int OH_Retrieval_DestroyRecord (OH_Retrieval_Record *record) | 销毁通过检索接口OH_Retrieval_Retrieve获得的检索结果。 |
| int OH_Retrieval_GetRecordLength (const OH_Retrieval_Record *record, uint32_t *length) | 获取检索结果OH_Retrieval_Record中的数据库bucket数组长度。 |
| int OH_Retrieval_GetRecordItem (const OH_Retrieval_Record *record, uint32_t index, const OH_Retrieval_RecordItem **item) | 获取检索结果OH_Retrieval_Record中的数据库bucket数组。 |
| int OH_Retrieval_GetItemSize (const OH_Retrieval_RecordItem *items, const char *fieldName, size_t *size) | 获取数据库bucket数组OH_Retrieval_RecordItem中指定字段的值的size。size值包含结束符。 |
| int OH_Retrieval_GetItemText (const OH_Retrieval_RecordItem *items, const char *fieldName, char *value, size_t size) | 获取数据库bucket数组OH_Retrieval_RecordItem中指定字段的值。 |

#### 类型定义说明

#### OH\_Retrieval\_Callback

```
typedef void (*OH_Retrieval_Callback)(void *context, OH_Retrieval_Record *record, int errCode)
```

**描述**

检索结果记录的回调函数。

**起始版本：** 6.0.0(20)

**参数:**

| 名称 | 描述 |
| --- | --- |
| context | 表示用户提供的上下文数据。 |
| record | 表示指向 OH_Retrieval_Record 实例的指针。 |
| errCode | 表示返回的错误码。 |

#### OH\_Retrieval\_Condition

```
typedef struct OH_Retrieval_Condition OH_Retrieval_Condition
```

**描述**

定义检索条件，可包含多个子检索条件。

**起始版本：** 6.0.0(20)

#### OH\_Retrieval\_Config

```
typedef struct OH_Retrieval_Config OH_Retrieval_Config
```

**描述**

定义检索器配置，包括数据库路径、数据库名称、包名等。

**起始版本：** 6.0.0(20)

#### OH\_Retrieval\_DbConfig

```
typedef struct OH_Retrieval_DbConfig OH_Retrieval_DbConfig
```

**描述**

定义一个用于打开数据库存储的数据库配置。

**起始版本：** 6.0.0(20)

#### OH\_Retrieval\_Query

```
typedef struct OH_Retrieval_Query OH_Retrieval_Query
```

**描述**

定义检索词，当前只支持纯文本检索，不支持图片、视频等。

**起始版本：** 6.0.0(20)

#### OH\_Retrieval\_Record

```
typedef struct OH_Retrieval_Record OH_Retrieval_Record
```

**描述**

定义检索结果，包含检索知识库得到的字段和字段取值。

**起始版本：** 6.0.0(20)

#### OH\_Retrieval\_RecordItem

```
typedef struct OH_Retrieval_RecordItem OH_Retrieval_RecordItem
```

**描述**

定义检索结果中的数据库bucket数组。

**起始版本：** 6.0.0(20)

#### OH\_Retrieval\_Retriever

```
typedef struct OH_Retrieval_Retriever OH_Retrieval_Retriever
```

**描述**

定义检索器类型，检索器是进行检索的句柄。

**起始版本：** 6.0.0(20)

#### OH\_Retrieval\_SubCondition

```
typedef struct OH_Retrieval_SubCondition OH_Retrieval_SubCondition
```

**描述**

定义子检索条件，目前支持向量检索。

**起始版本：** 6.0.0(20)

#### OH\_Retrieval\_VectorCondition

```
typedef struct OH_Retrieval_SubCondition OH_Retrieval_VectorCondition
```

**描述**

定义向量检索条件，包含检索的字段、检索参数、过滤条件等。

**起始版本：** 6.0.0(20)

#### Retrieval\_Channel\_Type

```
typedef enum Retrieval_Channel_Type Retrieval_Channel_Type
```

**描述**

定义数据索引类型，目前仅包括向量索引数据。

**起始版本：** 6.0.0(20)

#### 枚举类型说明

#### Retrieval\_Channel\_Type

```
enum Retrieval_Channel_Type
```

**描述**

定义数据索引类型，目前仅包括向量索引数据。

**起始版本：** 6.0.0(20)

| 枚举值 | 描述 |
| --- | --- |
| RETRIEVAL_TYPE_VECTOR | 表示向量索引。 |

#### 函数说明

#### OH\_Retrieval\_AddConfig()

```
int OH_Retrieval_AddConfig(OH_Retrieval_Config *config, Retrieval_Channel_Type channelType, OH_Retrieval_DbConfig *dbConfig)
```

**描述**

设置OH\_Retrieval\_Config中的数据库配置。

**起始版本：** 6.0.0(20)

**参数:**

| 名称 | 描述 |
| --- | --- |
| config | 指向检索配置 OH_Retrieval_Config 实例的指针。 |
| channelType | 表示一种数据索引类型，目前仅支持向量查询。 |
| dbConfig | 指向数据库配置实例的指针。 |

**返回：**

返回函数的执行状态。执行成功返回AIP\_OK。

| 错误码ID | 错误信息 |
| --- | --- |
| 0 | 操作成功 |
| 1021200010 | 无效参数 |

**参见：**

OH\_Retrieval\_Config、Retrieval\_Channel\_Type、OH\_Retrieval\_DbConfig、OH\_Aip\_ErrCode

#### OH\_Retrieval\_AddSubCondition()

```
int OH_Retrieval_AddSubCondition(OH_Retrieval_Condition *condition, OH_Retrieval_SubCondition *subCondition)
```

**描述**

在检索条件中，增加子检索条件。当前仅支持增加一个子检索条件。

**起始版本：** 6.0.0(20)

**参数:**

| 名称 | 描述 |
| --- | --- |
| condition | 指向检索条件OH_Retrieval_Condition实例的指针。 |
| subCondition | 指向子检索条件实例的指针，可以是向量检索条件OH_Retrieval_VectorCondition。 |

**返回：**

返回函数的执行状态。执行成功返回AIP\_OK。

| 错误码ID | 错误信息 |
| --- | --- |
| 0 | 操作成功 |
| 1021200009 | 条件数量超过上限1 |
| 1021200010 | 无效参数 |

**参见：**

OH\_Retrieval\_Condition、OH\_Retrieval\_SubCondition、OH\_Retrieval\_VectorCondition、OH\_Aip\_ErrCode

#### OH\_Retrieval\_CreateCondition()

```
OH_Retrieval_Condition *OH_Retrieval_CreateCondition()
```

**描述**

创建检索条件，作为检索接口的入参。

**起始版本：** 6.0.0(20)

**返回：**

函数执行成功时，返回指向检索条件OH\_Retrieval\_Condition实例的指针。当函数执行失败时，该指针为空指针。

**参见：**

OH\_Retrieval\_Condition

#### OH\_Retrieval\_CreateConfig()

```
OH_Retrieval_Config *OH_Retrieval_CreateConfig()
```

**描述**

获取检索器配置。用于初始化检索器。

**起始版本：** 6.0.0(20)

**返回：**

函数执行成功时，返回指向检索器配置OH\_Retrieval\_Config实例的指针。当函数执行失败时，该指针为空指针。

**参见：**

OH\_Retrieval\_Config、OH\_Aip\_ErrCode

#### OH\_Retrieval\_CreateDbConfig()

```
OH_Retrieval_DbConfig *OH_Retrieval_CreateDbConfig()
```

**描述**

创建一个数据库相关配置项。

**起始版本：** 6.0.0(20)

**返回：**

返回指向OH\_Retrieval\_DbConfig实例的指针。当函数执行失败时，该指针为空指针。

**参见：**

OH\_Retrieval\_DbConfig、OH\_Aip\_ErrCode

#### OH\_Retrieval\_CreateQuery()

```
OH_Retrieval_Query *OH_Retrieval_CreateQuery()
```

**描述**

创建检索词，作为检索接口的入参。

**起始版本：** 6.0.0(20)

**返回：**

函数执行成功时，返回指向OH\_Retrieval\_Query实例的指针。当函数执行失败时，该指针为空指针。

**参见：**

OH\_Retrieval\_Query

#### OH\_Retrieval\_CreateRetriever()

```
int OH_Retrieval_CreateRetriever(const OH_Retrieval_Config *config, OH_Retrieval_Retriever **retriever)
```

**描述**

读取检索配置，初始化检索器。

**起始版本：** 6.0.0(20)

**参数:**

| 名称 | 描述 |
| --- | --- |
| config | 创建检索器时，需要输入检索器的配置项OH_Retrieval_Config。 |
| retriever | 返回指向检索器OH_Retrieval_Retriever实例的指针。 |

**返回：**

返回函数的执行状态。执行成功返回AIP\_OK。

| 错误码ID | 错误信息 |
| --- | --- |
| 0 | 操作成功 |
| 1021200010 | 无效参数 |

**参见：**

OH\_Retrieval\_Retriever、OH\_Retrieval\_Config、OH\_Aip\_ErrCode

#### OH\_Retrieval\_CreateVectorCondition()

```
OH_Retrieval_VectorCondition *OH_Retrieval_CreateVectorCondition()
```

**描述**

创建向量检索条件。

**起始版本：** 6.0.0(20)

**返回：**

函数执行成功时，返回指向检索条件OH\_Retrieval\_VectorCondition实例的指针。当函数执行失败时，该指针为空指针。

**参见：**

OH\_Retrieval\_VectorCondition

#### OH\_Retrieval\_DestroyCondition()

```
int OH_Retrieval_DestroyCondition(OH_Retrieval_Condition *condition)
```

**描述**

销毁通过OH\_Retrieval\_CreateCondition获得的检索条件。

**起始版本：** 6.0.0(20)

**参数:**

| 名称 | 描述 |
| --- | --- |
| condition | 指向检索条件OH_Retrieval_Condition的指针。 |

**返回：**

返回函数的执行状态。执行成功返回AIP\_OK。

| 错误码ID | 错误信息 |
| --- | --- |
| 0 | 操作成功 |
| 1021200010 | 无效参数 |

**参见：**

OH\_Retrieval\_Condition、OH\_Aip\_ErrCode、OH\_Retrieval\_CreateCondition

#### OH\_Retrieval\_DestroyConfig()

```
int OH_Retrieval_DestroyConfig(OH_Retrieval_Config *config)
```

**描述**

销毁通过OH\_Retriever\_CreateConfig获得的检索配置。

**起始版本：** 6.0.0(20)

**参数:**

| 名称 | 描述 |
| --- | --- |
| config | 指向检索配置OH_Retrieval_Config的指针。 |

**返回：**

返回函数的执行状态。执行成功返回AIP\_OK。

| 错误码ID | 错误信息 |
| --- | --- |
| 0 | 操作成功 |
| 1021200010 | 无效参数 |

**参见：**

OH\_Retrieval\_Config、OH\_Aip\_ErrCode、OH\_Retrieval\_CreateConfig

#### OH\_Retrieval\_DestroyDbConfig()

```
int OH_Retrieval_DestroyDbConfig(OH_Retrieval_DbConfig *dbConfig)
```

**描述**

销毁OH\_Retrieval\_CreateDbConfig创建的OH\_Retrieval\_DbConfig。

**起始版本：** 6.0.0(20)

**参数:**

| 名称 | 描述 |
| --- | --- |
| dbConfig | 表示指向OH_Retrieval_DbConfig实例的指针。 |

**返回：**

返回函数的执行状态。执行成功返回AIP\_OK。

| 错误码ID | 错误信息 |
| --- | --- |
| 0 | 操作成功 |
| 1021200010 | 无效参数 |

**参见：**

OH\_Retrieval\_DbConfig、OH\_Aip\_ErrCode、OH\_Retrieval\_CreateDbConfig

#### OH\_Retrieval\_DestroyQuery()

```
int OH_Retrieval_DestroyQuery(OH_Retrieval_Query *query)
```

**描述**

销毁通过OH\_Retrieval\_CreateQuery获得的检索词。

**起始版本：** 6.0.0(20)

**参数:**

| 名称 | 描述 |
| --- | --- |
| query | 指向检索词OH_Retrieval_Query的指针。 |

**返回：**

返回函数的执行状态。执行成功返回AIP\_OK。

| 错误码ID | 错误信息 |
| --- | --- |
| 0 | 操作成功 |
| 1021200010 | 无效参数 |

**参见：**

OH\_Retrieval\_Query、OH\_Aip\_ErrCode、OH\_Retrieval\_CreateQuery

#### OH\_Retrieval\_DestroyRecord()

```
int OH_Retrieval_DestroyRecord(OH_Retrieval_Record *record)
```

**描述**

销毁通过检索接口OH\_Retrieval\_Retrieve获得的检索结果。

**起始版本：** 6.0.0(20)

**参数:**

| 名称 | 描述 |
| --- | --- |
| record | 指向检索结果OH_Retrieval_Record的指针。 |

**返回：**

返回函数的执行状态。执行成功返回AIP\_OK。

| 错误码ID | 错误信息 |
| --- | --- |
| 0 | 操作成功 |
| 1021200010 | 无效参数 |

**参见：**

OH\_Retrieval\_Record、OH\_Aip\_ErrCode、OH\_Retrieval\_Retrieve

#### OH\_Retrieval\_DestroyRetriever()

```
int OH_Retrieval_DestroyRetriever(OH_Retrieval_Retriever *retriever)
```

**描述**

销毁通过OH\_Retrieval\_CreateRetriever获得的检索器。

**起始版本：** 6.0.0(20)

**参数:**

| 名称 | 描述 |
| --- | --- |
| retriever | 指向检索器OH_Retrieval_Retriever的指针。 |

**返回：**

返回函数的执行状态。执行成功返回AIP\_OK。

| 错误码ID | 错误信息 |
| --- | --- |
| 0 | 操作成功 |
| 1021200010 | 无效参数 |

**参见：**

OH\_Retrieval\_Retriever、OH\_Aip\_ErrCode、OH\_Retrieval\_CreateRetriever

#### OH\_Retrieval\_DestroySubCondition()

```
int OH_Retrieval_DestroySubCondition(OH_Retrieval_SubCondition *condition)
```

**描述**

销毁通过OH\_Retrieval\_SubCondition。

**起始版本：** 6.0.0(20)

**参数:**

| 名称 | 描述 |
| --- | --- |
| condition | 指向检索条件OH_Retrieval_SubCondition的指针。 |

**返回：**

返回函数的执行状态。执行成功返回AIP\_OK。

| 错误码ID | 错误信息 |
| --- | --- |
| 0 | 操作成功 |
| 1021200010 | 无效参数 |

**参见：**

OH\_Retrieval\_SubCondition、OH\_Aip\_ErrCode

#### OH\_Retrieval\_DestroyVectorCondition()

```
int OH_Retrieval_DestroyVectorCondition(OH_Retrieval_VectorCondition *condition)
```

**描述**

销毁通过OH\_Retrieval\_CreateVectorCondition获得的检索条件。

**起始版本：** 6.0.0(20)

**参数:**

| 名称 | 描述 |
| --- | --- |
| condition | 指向向量检索条件OH_Retrieval_VectorCondition的指针。 |

**返回：**

返回函数的执行状态。执行成功返回AIP\_OK。

| 错误码ID | 错误信息 |
| --- | --- |
| 0 | 操作成功 |
| 1021200010 | 无效参数 |

**参见：**

OH\_Retrieval\_VectorCondition、OH\_Aip\_ErrCode、OH\_Retrieval\_CreateVectorCondition

#### OH\_Retrieval\_GetItemSize()

```
int OH_Retrieval_GetItemSize(const OH_Retrieval_RecordItem *items, const char *fieldName, size_t *size)
```

**描述**

获取数据库bucket数组OH\_Retrieval\_RecordItem中指定字段的值的size。size值包含结束符。

**起始版本：** 6.0.0(20)

**参数:**

| 名称 | 描述 |
| --- | --- |
| items | 指向数据库bucket数组OH_Retrieval_RecordItem实例的指针。 |
| fieldName | 数据库bucket的字段名。 |
| size | 数据库bucket相应字段的值的大小。 |

**返回：**

返回函数的执行状态。执行成功返回AIP\_OK。

| 错误码ID | 错误信息 |
| --- | --- |
| 0 | 操作成功 |
| 1021200007 | 不存在该字段 |
| 1021200010 | 无效参数 |

**参见：**

OH\_Retrieval\_RecordItem、OH\_Aip\_ErrCode

#### OH\_Retrieval\_GetItemText()

```
int OH_Retrieval_GetItemText(const OH_Retrieval_RecordItem *items, const char *fieldName, char *value, size_t size)
```

**描述**

获取数据库bucket数组OH\_Retrieval\_RecordItem中指定字段的值。

**起始版本：** 6.0.0(20)

**参数:**

| 名称 | 描述 |
| --- | --- |
| items | 指向数据库bucket数组OH_Retrieval_RecordItem实例的指针。 |
| fieldName | 数据库bucket的字段名。 |
| value | 数据库bucket相应字段的值。 |
| size | 数据库bucket相应字段的值的大小。 |

**返回：**

返回函数的执行状态。执行成功返回AIP\_OK。

| 错误码ID | 错误信息 |
| --- | --- |
| 0 | 操作成功 |
| 1021200007 | 不存在该字段 |
| 1021200010 | 无效参数 |

**参见：**

OH\_Retrieval\_RecordItem、OH\_Aip\_ErrCode

#### OH\_Retrieval\_GetRecordItem()

```
int OH_Retrieval_GetRecordItem(const OH_Retrieval_Record *record, uint32_t index, const OH_Retrieval_RecordItem **item)
```

**描述**

获取检索结果OH\_Retrieval\_Record中的数据库bucket数组。

**起始版本：** 6.0.0(20)

**参数:**

| 名称 | 描述 |
| --- | --- |
| record | 指向检索结果OH_Retrieval_Record实例的指针。 |
| index | record数组的索引值。最大值为999。 |
| item | 指向record数组中单个元素OH_Retrieval_RecordItem的指针。 |

**返回：**

返回函数的执行状态。执行成功返回AIP\_OK。

| 错误码ID | 错误信息 |
| --- | --- |
| 0 | 操作成功 |
| 1021200006 | 下标越界 |
| 1021200010 | 无效参数 |

**参见：**

OH\_Retrieval\_Record、OH\_Retrieval\_RecordItem、OH\_Aip\_ErrCode

#### OH\_Retrieval\_GetRecordLength()

```
int OH_Retrieval_GetRecordLength(const OH_Retrieval_Record *record, uint32_t *length)
```

**描述**

获取检索结果OH\_Retrieval\_Record中的数据库bucket数组。

**起始版本：** 6.0.0(20)

**参数:**

| 名称 | 描述 |
| --- | --- |
| record | 指向检索结果OH_Retrieval_Record实例的指针。 |
| length | 数据库bucket数组的长度。 |

**返回：**

返回函数的执行状态。执行成功返回AIP\_OK。

| 错误码ID | 错误信息 |
| --- | --- |
| 0 | 操作成功 |
| 1021200010 | 无效参数 |

**参见：**

OH\_Retrieval\_Record、OH\_Aip\_ErrCode

#### OH\_Retrieval\_Retrieve()

```
int OH_Retrieval_Retrieve(const OH_Retrieval_Retriever *retriever, const OH_Retrieval_Query *query, const OH_Retrieval_Condition *condition, void *context, const OH_Retrieval_Callback *callback)
```

**描述**

执行检索。获得检索器句柄后，输入检索查询词，根据检索条件执行检索，得到检索结果。接口执行时，会在“/data/storage/el2/base/cache”路径下生成临时存储缓存文件。当设备类型为phone、tablet时，该接口仅支持倒排，不支持向量。该接口调用需注意在callback回调未触发前不能释放传入接口参数指针的内存，否则可能导致程序异常。

**起始版本：** 6.0.0(20)

**参数:**

| 名称 | 描述 |
| --- | --- |
| retriever | 检索器句柄，指向OH_Retrieval_Retriever实例的指针。 |
| query | 检索的查询词，指向OH_Retrieval_Query实例的指针。 |
| condition | 检索条件，指向OH_Retrieval_Condition实例的指针。 |
| context | 表示用户提供的上下文数据，这些数据将在后续调用函数时传递回函数中。 |
| callback | 表示指向OH_Retrieval_Callback实例的指针。 |

**返回：**

返回函数的执行状态。执行成功返回AIP\_OK。

| 错误码ID | 错误信息 |
| --- | --- |
| 0 | 操作成功 |
| 1021200005 | 执行报错 |
| 1021200010 | 无效参数 |
| 1021200012 | 无法生成嵌入向量 |

**参见：**

OH\_Retrieval\_Retriever、OH\_Retrieval\_Query、OH\_Retrieval\_Condition、OH\_Retrieval\_Callback、OH\_Aip\_ErrCode

#### OH\_Retrieval\_SetDbConfig()

```
int OH_Retrieval_SetDbConfig(OH_Retrieval_DbConfig *dbConfig, OH_Rdb_ConfigV2 *rdbConfig)
```

**描述**

在OH\_Retrieval\_DbConfig中设置数据库配置。

**起始版本：** 6.0.0(20)

**参数:**

| 名称 | 描述 |
| --- | --- |
| dbConfig | 表示指向OH_Retrieval_DbConfig实例的指针。 |
| rdbConfig | 表示指向数据库配置实例的指针，可能是OH_Rdb_ConfigV2实例。 |

**返回：**

返回函数的执行状态。执行成功返回AIP\_OK。

| 错误码ID | 错误信息 |
| --- | --- |
| 0 | 操作成功 |
| 1021200010 | 无效参数 |

**参见：**

OH\_Retrieval\_DbConfig、OH\_Rdb\_ConfigV2、OH\_Aip\_ErrCode

#### OH\_Retrieval\_SetOriginalQuestion()

```
int OH_Retrieval_SetOriginalQuestion(OH_Retrieval_Query *query, const char *question)
```

**描述**

设置OH\_Retrieval\_Query中的检索词。

**起始版本：** 6.0.0(20)

**参数:**

| 名称 | 描述 |
| --- | --- |
| query | 指向检索词OH_Retrieval_Query实例的指针。 |
| question | 纯文本的问题。 |

**返回：**

返回函数的执行状态。执行成功返回AIP\_OK。

| 错误码ID | 错误信息 |
| --- | --- |
| 0 | 操作成功 |
| 1021200008 | 数组超过最大长度512字节 |
| 1021200010 | 无效参数 |

**参见：**

OH\_Retrieval\_Query、OH\_Aip\_ErrCode

#### OH\_Retrieval\_SetSimilarityThreshold()

```
int OH_Retrieval_SetSimilarityThreshold(OH_Retrieval_VectorCondition *condition, double threshold)
```

**描述**

在检索条件中，设置向量检索的相似度阈值。

**起始版本：** 6.0.0(20)

**参数:**

| 名称 | 描述 |
| --- | --- |
| condition | 指向检索条件OH_Retrieval_VectorCondition实例的指针。 |
| threshold | 向量检索的余弦相似度阈值，取值范围[0, 1]。 |

**返回：**

返回函数的执行状态。执行成功返回AIP\_OK。

| 错误码ID | 错误信息 |
| --- | --- |
| 0 | 操作成功 |
| 1021200010 | 无效参数 |

**参见：**

OH\_Retrieval\_VectorCondition、OH\_Aip\_ErrCode

#### OH\_Retrieval\_SetVectorRecallLimit()

```
int OH_Retrieval_SetVectorRecallLimit(OH_Retrieval_VectorCondition *condition, uint32_t limit)
```

**描述**

在检索条件中，设置向量检索结果数量上限。

**起始版本：** 6.0.0(20)

**参数:**

| 名称 | 描述 |
| --- | --- |
| condition | 指向检索条件OH_Retrieval_VectorCondition实例的指针。 |
| limit | 向量检索结果的数量上限，最大值1000。 |

**返回：**

返回函数的执行状态。执行成功返回AIP\_OK。

| 错误码ID | 错误信息 |
| --- | --- |
| 0 | 操作成功 |
| 1021200010 | 无效参数 |

**参见：**

OH\_Retrieval\_VectorCondition、OH\_Aip\_ErrCode