商品检索服务的数据库层支持图像存储和检索，您可以通过POST方式调用该服务提供的接口，对数据库中的数据进行增加、查询、删除、检索及清理操作。本文介绍各接口的详细信息，包括POST内容示例、输入参数、输出参数及输出示例。
商品检索服务的数据库层提供的接口列表如下：在数据库中，每张图片数据必须指定对应的group_id，从而实现后续的查询和检索功能。下文详细介绍数据库层提供的接口，此处仅介绍每个接口的特有参数，关于接口中的通用参数说明请参见接口格式及调用说明（必读）。
注册数据（db_set）
注册数据指用户向服务内指定的数据库添加数据。您可以上传图片数据，并为该数据指定group_id和intra_id，进而为数据库添加该数据。如果您是OSS用户，还可以将上传的Base 64编码的图像内容写到指定路径下。
以下介绍该接口的调用示例及参数说明：
- POST内容示例（单图像注册）
{ "function_name": "db_set", "function_params": { "database_name":"libai", "image" : base64.b64encode(open(image_path, 'rb').read()).decode(ENCODING), #图像的Base 64编码。 "group_id" : "1", "savename" : imagea }, } - 输入参数说明
参数 是否必选 描述 示例值 类型 image 是 图片内容的Base 64编码字符串。如果您是OSS 用户，则该参数可以填写图片对应的OSS地址。 无 STRING group_id 是 注册单张图片必须指定的ID信息。 "1" STRING intra_id 否 同一个group_id下的内部ID。如果没有指定该参数，则默认递增。 None INT savename 否 OSS后端限定参数。 如果传入的image是Base 64编码，则指定该参数可以把图片写入到您提供的root_path/database_name/savename下。 "xxx.jpg" STRING data 否 Elasticsearch后端限定参数。您可以将data的附加信息写入到该条特征对应的doc中。 [] DICT - 输出参数说明
参数 描述 示例值 类型 request_id 请求的唯一标识。 "54092937-191e-45b6-8be4-415b45a4****"STRING success 请求是否成功，取值包括： - true：请求成功。
- false：请求失败。
true BOOL info 返回调用函数的相关信息。 {"add": true}DICT error_code 请求失败时，返回的错误码。 None INT error_msg 请求失败时，返回的错误信息。 None STRING - 输出示例
{ "request_id": "54092937-191e-45b6-8be4-415b45a4****", "success": true, "info": {"add": true} }
查询数据（db_get）
查询数据指用户向服务内指定的数据库查询指定group_id及intra_id的数据，该接口支持通过以下两种方式查询数据：
- 指定group_id进行查询，接口返回数据库内所有符合该group_id的相关信息。
- 指定group_id和intra_id进行查询，接口返回数据库内符合查询条件的唯一数据记录的相关信息。
以下介绍该接口的调用示例及参数说明：
- POST内容示例
{ "function_name": "db_get", # 查询数据的操作名称。 "function_params": { "database_name":"test", # 用户指定的数据库名称。 "group_id" : "6000" # 待查询的ID信息。 "intra_id" : 1 # 待查询的数据内部的ID，选填。 }, } - 输入参数说明
参数 是否必选 描述 示例值 类型 database_name 是 在该数据库内查询数据。 "test" STRING group_id 是 待查询数据的group_id。 "6000" STRING intra_id 否 待查询数据的intra_id。如果未指定该参数，则接口返回数据库内所有符合group_id的相关信息。 0 INT source 否 Elasticsearch后端限定参数，限定返回doc里面的内容。您可以通过数据库管理层的get接口查看doc，通常doc可以包括： - "group_id"
- "intra_id"
- "_id"
- "feature"
["group_id", "intra_id"]LIST/None - 输出参数说明
参数 描述 示例值 类型 request_id 请求的唯一标识。 "a666a783-b6a9-49ca-a5fb-e9c1091e****"STRING success 请求是否成功，取值包括： - true：请求成功。
- false：请求失败。
true BOOL status 是否查询到指定数据，取值包括： - true：查询成功。
- false：查询失败。
true BOOL info 如果查询成功，则返回查询到的信息，包括数据ID和地址信息。如果查询失败，则返回相关提示。 {"oss_path_name": ["oss://xxxxx/xxxx.jpg"],"group_id": ["test_group_id"],"intra_id": [0.0]}DICT error_code 请求失败时，返回的错误码。 None INT error_msg 请求失败时，返回的错误信息。 None STRING - 输出示例
{ "request_id": "a666a783-b6a9-49ca-a5fb-e9c1091e****", "success": true, "status": true, "info": { "oss_path_name": ["oss://xxxxx/xxxx.jpg"], "group_id": ["test_group_id"], "intra_id": [0.0] } }
删除数据（db_delete）
删除数据指用户向服务内指定的数据库删除指定group_id及intra_id的数据，该接口支持通过以下两种方式删除数据：
- 指定group_id进行删除，可以删除数据库内所有符合该group_id的相关信息。
- 指定group_id和intra_id进行删除，仅删除数据库内符合条件的唯一数据记录的相关信息。
以下介绍该接口的调用示例及参数说明：
- POST内容示例
{ "function_name": "db_delete", # 删除数据的操作名称。 "function_params": { "database_name":"test", # 用户指定的数据库名称。 "group_id" : "test_gid" # 待删除的ID信息。 "intra_id" : 0 # 待删除的数据内部的ID，选填。 }, } - 输入参数说明
参数 是否必选 描述 示例值 类型 database_name 是 在该数据库中删除数据。 "test" STRING group_id 是 待删除数据的group_id。 "test_gid" STRING intra_id 否 待删除数据的intra_id，如果未指定，则删除group_id对应的所有数据。 0 INT - 输出参数说明
字段 描述 示例值 类型 request_id 请求的唯一标识。 "e8a8c95e-d2e2-4b68-b403-2fc90bbc****"STRING success 请求是否成功，取值包括： - true：请求成功。
- false：请求失败。
true BOOL status 是否删除成功，取值包括： - true：删除成功。
- false：删除失败。如果数据不存在，则返回false。
true BOOL info 返回删除的相关信息。 'database delete instruction params must contains group_id'STRING error_code 请求失败时，返回的错误码。 None INT error_msg 请求失败时，返回的错误信息。 None STRING - 输出示例
{ "request_id": "e8a8c95e-d2e2-4b68-b403-2fc90bbc****", "success": true, "status": true, "info": "database delete gid xxx" }
检索数据（db_search）
检索数据指用户向服务内指定的数据库发送图片检索请求，系统会提取该图片的特征，并在已注册的数据中找到与该特征最接近的特征对应的图片，进而返回该图片的相关信息。该接口支持以下检索策略：
- 与注册数据类似，检索数据支持输入图片的OSS地址或Base 64编码。
- 检索数据可以指定TOPK距离的召回。
- 检索数据可以指定是否返回被检索到图片的原始数据地址，默认不返回。
以下介绍该接口的调用示例及参数说明：
- POST内容示例
{ "function_name": "db_search", "function_params": { "database_name":"libai", #待检索的数据库名称。 "image" : base64.b64encode(open(imagea, 'rb').read()).decode(ENCODING), #待检索图像的Base 64编码。 'search_topk' : 2, # 检索返回的TOPK。 }, } - 输入参数说明
参数 是否必选 描述 示例值 类型 database_name 是 在该数据库中检索图片。 "libai" STRING image 是 图片内容的Base 64编码字符串。OSS用户也可以将该参数配置为图片的OSS地址。 无 STRING search_topk 是 检索返回的记录数目。 3 INT savename 否 OSS后端限定参数。 如果传入的image为Base 64编码，则指定该参数可以将图片写入到您提供的root_path/database_name/savename下。 "xxx.jpg" STRING search_algorithm 否 Elasticsearch后端限定参数，取值包括： - "hnsw"： 近邻召回，速度快，但是不能保证全部召回。
- "linear"： 线性召回，能够保证召回结果的正确性。
"hnsw" STRING - 输出参数说明
参数 描述 示例值 Type request_id 请求的唯一标识。 "8549fde3-cd2d-4053-a3a4-fb86127b****"STRING success 请求是否成功，取值包括： - true：请求成功。
- false：请求失败。
true BOOL status 检索是否成功，取值包括： - true：检索成功。
- false：检索失败。
true BOOL info 检索返回的信息，不同后端返回的数据结构请参见下方的info的数据结构。 无 DICT error_code 请求失败时，返回的错误码。 None INT error_msg 请求失败时，返回的错误信息。 None STRING 表 1. info的数据结构 后端类型 数据结构 描述 OSS ['distance', 'group_id','intra_id', 'oss_path_name']数据结构中的参数含义如下： - 'distance'：检索的距离列表。如果是Cosine距离，则数值越大表示结果越接近。如果是SquaredEuclidean距离，则数值越小表示结果越接近。
- 'group_id'：检索到的图片'group_id'列表。
- 'intra_id'：检索到的图片'intra_id'列表。
- 'oss_path_name'：检索到的原数据地址列表。
Elasticsearch ['total', 'max_score', 'hits']数据结构中的参数含义如下： - 'total'：返回的记录总数量。
- 'max_score'：检索的距离得分，代表距离远近，数值越大表示结果越近。
- 'hits'：检索到的Elasticsearch后端存储的Documents，包含
['_index', '_type', '_id', '_score', '_source']信息，每个字段的含义如下：- '_index'：Elasticsearch后端中存储的数据库名称，与database_name取值相同。
- '_type'：返回的类型。
- '_id'：检索到的记录的在Elasticsearch中的唯一标识。
- '_score'：距离检索的得分，得分越大，距离越近。
- '_source'：检索返回的源数据内容。
- 输出示例
{ "request_id": "8549fde3-cd2d-4053-a3a4-fb86127b****", "success": true, 'status': True, 'info': { 'distance': [0.29342561960220337, 0.287186861038208, 0.27671411633491516, 0.2678218483924866, 0.2663806676864624], 'group_id': ['xxgid1', 'xxgid1', 'xxgid1', 'xxgid1', 'xxgid1'], 'intra_id': [0.0, 6.0, 2.0, 7.0, 4.0]} }