文档目录
从这里开始
REST API参考
索引和搜索文档注解API 鉴权对象操作批量对象操作创建单个对象创建或更新单个对象删除单个对象搜索对象搜索参数查询任务状态支持数据类型API错误码

注:卡拉搜索目前正在封闭内测,如果你感兴趣在你的项目中使用卡拉搜索,请邮件我们,邮件地址是 kalasearch@gmail.com

REST API


本文主要面向直接用 RESTful API 请求卡拉搜索的用户,或 SDK 开发者,对绝大多数用户,请直接使用卡拉搜索提供的 SDK

为了保证速度,卡拉搜索的引擎和所有服务构建在一个 HTTP 服务器上,所有的外部通讯任务均由 REST API 承担。因此,所有用 SDK 可以完成的操作用 REST API 均可以完成。事实上,卡拉搜索的所有 SDK 都是在 REST API 上进行的封装。

如果我们暂时没有支持你所常用的语言或框架,不用着急,你可以考虑直接集成 REST API 来接入卡拉搜索。在本文中,我们介绍所有可用 REST API 的端点、参数,并给出例子方便调试。

文档注解

请注意,下文中所有用花括号的地方,如 v1/indexes/{indexId}/batch 里的 {indexId} 均代表一个可替代的变量。

比如这里的 {indexId} 代表你应该将 {indexId} 替换为你的索引的具体的 ID。如果需要获取索引的 ID,登录卡拉搜索后台后即可找到。

API 鉴权


为了保护数据安全,每次 API 请求我们都需要你在请求的 Header 中提供 X-Kalasearch-Id (下文简称 AppId)和 X-Kalasearch-Key (下文简称 Api Key)

X-Kalasearch-Id 代表你请求的对应 App 的 Id。在卡拉搜索后台,你可以看到你所创建的所有 App,每个 App 都有自己的一个唯一 id

X-Kalasearch-Key 代表你请求的 App 对应的密钥,可以简单把它想象成密码,只有密码正确,卡拉搜索才会让请求通过

X-Kalasearch-IdX-Kalasearch-Key这两者可以在卡拉搜索后台界面很容易找到,在请求时请将这二者置于 HTTP 请求的 header 中,如下文例子中所示。

请注意,每个 API 密钥都有其对应的读写权限。如果在前端使用(如网页、APP 内等)请使用只读密钥。对于详细的数据安全建议,请参考: 数据安全

对象操作


在卡拉搜索中,存储的数据单元是对象,即Object。在卡拉搜索后台建立好索引之后,你可以立即开始尝试添加对象至索引中,之后,即可开始搜索添加的对象了。

有时在搜索引擎领域的术语里,“对象”通常也被叫作“文档”。

请注意,这里的 对象 是泛指你可能用于搜索的数据。比如,如果你的业务是电商,那么对于你而言一个对象更有可能是一件商品的信息;而如果你的业务是游戏,那么对你而言,一个对象可能是一位玩家或一件装备的数据。

将对象添加到索引,进行更新或者删除的操作我们统称为对象操作,下表中列出所有对象操作可能用到的端点。

我们强烈推荐使用批量操作的端点来减少上传时间和加快索引速度,请参考并优先使用下表中批量创建或更新对象,批量删除对象等端点。

HTTP端点说明
POST/v1/indexes/{indexId}/batch批量对象操作
PUT/v1/indexs/{indexId}/objects/{objectId}创建或更新单个对象 - 指定对象 ID
POST/v1/indexs/{indexId}/objects/{objectId}创建单个对象 - 不指定对象 ID
DELETE/v1/indexs/{indexId}/objects/{objectId}删除单个对象

批量对象操作


当数据较多时,你可以将多个对象操作置于一个请求中,以减少网络传输次数。批量请求可以大大减少上传索引时间并提高效率,因此我们推荐所有的对象操作都用批量操作来进行。

每个批量请求最大支持 10MB 请求大小,或 1000 个对象操作

目前引擎支持指定以下几种操作类型(actionType)

  • UPDATE_OBJECT: 添加或更新对象(提供 ID)- 推荐用于数据上传,须提供objectId
  • ADD_OBJECT: 添加对象(不提供 ID,随机生成 ID) - 不提供objectId,引擎自动生成
  • DELETE_OBJECT: 删除对象 - 必须指定objectId

请注意在单个请求中,仅允许含有一种单一类型的操作,比如不能够第一个为UPDATE_OBJECT操作而第二个为DELETE_OBJECT。在进行批量操作前,引擎会验证请求合法性。如果请求不合法,则不会进行任何对象操作。如果请求合法,则会执行所有对象操作。

使用数据库 ID 为索引对象的 ID

通常在你的数据库中,每条数据已有某种形式的 ID。比如说对于一个商品数据表来说,商品 ID 就是商品表的主键 ID。这些 ID 可能是连续自增的,也可能是数据库随机生成的 UUID。

我们推荐多数情况下在卡拉搜索中使用数据库本身的 ID 来保持 ID 的一致,这样做有一系列好处,比如方便你进行数据的同步和修改。使用本端点来上传数据时,只需指定对象 ID 为你的数据的 ID,则可以保证卡拉搜索中使用 ID 与数据库中的 ID一致。

因此,为了最大限度地方便之后的维护,我们强烈推荐使用数据库本身的 ID 作为引擎中的 ID。如果你希望让引擎在索引时生成一个 ID 的话,则可能需要在数据库中记录引擎返回的 ID,以方便之后进行更新或删除操作。如果希望使用数据库的 ID 作为索引 ID,请指定 actionTypeUPDATE_OBJECT并提供objectId(见下文示例)。

POST
https://api.kalasearch.cn/v1/indexes/{indexId}/batch

请求参数

参数描述说明
名为 actions的 JSON 对象数组JSON 格式的对象组成的数组actions 数组中每个元素必须含有 actionType,可能含有 bodyobjectId 字段

批量添加或更新对象

在请求中指定每个操作为UPDATE_OBJECT并提供objectId,这样引擎会使用你提供的objectId来作为引擎的对象主键。如上文所述,我们建议将你的数据库主键作为objectId

下面示例中,我们假设数据库中有两条电影数据,它们的数据库 ID 分别是 1001 和 1002,我们可以按如下组织请求格式来进行批量添加。

在索引时,数字类型的 objectId 会被转化为字符串类型,而字符串类型不做任何处理

请求示例

curl --location --request POST 'https://api.kalasearch.cn/v1/indexes/501f6a76-c5f1-4e88-874c-dd33cd11c704/batch' \
--header 'X-Kalasearch-Id: 114a68ad-f8cb-485c-9ca3-e8f8692f5966' \
--header 'X-Kalasearch-Key: 44e763bc-0c61-4716-a5c7-0a77c3a96b11' \
--header 'Content-Type: application/json' \
--data-raw '{
"actions": [
{
"actionType": "UPDATE_OBJECT",
"objectId": 1001,
"body": {
"name": "大话西游",
"actors": "周星驰",
"year": 1998
}
},
{
"actionType": "UPDATE_OBJECT",
"objectId": 1002,
"body": {
"name": "无间道",
"actors": "刘德华",
"year": 2000
}
}
]
}'

请注意,如果在引擎中已经存在objectId10011002的对象,则对应的对象会被更新。因此,如果用数据库主键作为 ID,在需要更新和删除时可以统一用同样的 ID 进行操作(示例见下文)

返回示例 200

{
"jobId": "d8a73953-b9bd-4bdc-85dc-65abc3b14afd",
"jobStatus": "PENDING",
"objectIds": [
"1001",
"1002"
]
}

批量创建对象

批量创建对象与上文中的指定objectId批量创建对象类似,只需要指定每个操作的类型为ADD_OBJECT即可。引擎会为每个对象分配一个objectId并返回。

请求示例

{
"actions": [
{
"actionType": "ADD_OBJECT",
"body": {
"name": "大话西游",
"actors": "周星驰",
"year": 1998
}
},
{
"actionType": "ADD_OBJECT",
"body": {
"name": "无间道",
"actors": "刘德华",
"year": 2000
}
}
]
}

返回示例 200

{
"jobId": "1304ecd2-2f4a-4807-a54e-2650ed4e3b22",
"jobStatus": "PENDING",
"objectIds": [
"t8lyLHYBSDaLYv25sYUF",
"uMlyLHYBSDaLYv25sYUF"
]
}

批量删除对象

批量删除对象仅需指定actionTypeDELETE_OBJECT并提供objectId即可。

请求示例

{
"actions": [
{
"actionType": "DELETE_OBJECT",
"objectId": 1001
},
{
"actionType": "DELETE_OBJECT",
"objectId": 1002
}
]
}

返回示例 200

{
"jobId": "43bda189-813d-4cc7-a4f5-8bcff7d7cb9f",
"jobStatus": "COMPLETED",
"objectIds": [
"1001",
"1002"
]
}

返回项和错误码

返回项描述说明
jobId提交的任务 id如需查询任务状态需要用到这个 id
jobStatus任务运行状态,刚提交或运行中的任务为 PENDING
objectIds索引对象的 id 列表,对应上传的对象的顺序

请注意,这里返回成功是指成功提交了一个添加对象的后台任务。具体的任务完成需要一定的时间,取决于队列中的任务量,通常在数秒到数十秒内完成。

如果需要查询提交的任务完成状态,请用查询任务状态端点。

错误信息

HTTP状态码返回消息(message)说明
404index does not exist索引不存在,请检查indexId参数
400Unable to process JSONbody格式不正确,请用 json检查器 检查格式
400INPUT_NOT_VALIDbatch 请求格式不正确,请查看 message 以改正请求格式 json检查器 检查格式

创建单个对象


创建单个对象时,引擎会随机为对象生成一个 id,因此无法指定对象 ID。如需使用数据库对应的 ID,请参考创建或更新单个对象

POST
https://api.kalasearch.cn/v1/indexes/{indexId}/objects

请求参数

参数描述说明
JSON 格式的数据单个 JSON 格式的对象

请求示例

curl --location --request POST 'https://api.kalasearch.cn/v1/indexes/501f6a76-c5f1-4e88-874c-dd33cd11c704/objects' \
--header 'X-Kalasearch-Id: 114a68ad-f8cb-485c-9ca3-e8f8692f5966' \
--header 'X-Kalasearch-Key: 44e763bc-0c61-4716-a5c7-0a77c3a96b11' \
--header 'Content-Type: application/json' \
--data-raw '{
"name": "大话西游",
"actors": "周星驰/吴孟达",
"year": 1998
}'

返回示例 200

{
"jobId": "dc533e68-dff3-40c0-b848-a4bac8d0d056",
"jobStatus": "PENDING",
"objectId": "v_pFJ3YBESLUziTkJB6M"
}
返回项描述说明
jobId提交的任务 id如需查询任务状态需要用到这个 id
jobStatus任务运行状态,刚提交或运行中的任务为 PENDING
objectId为对象生成的 id

请注意,这里返回成功是指成功提交了一个添加对象的后台任务。具体的任务完成需要一定的时间,取决于队列中的任务量,通常在数秒到数十秒内完成。

如果需要查询提交的任务完成状态,请用查询任务状态端点。

错误信息

HTTP状态码返回消息(message)说明
404index does not exist索引不存在,请检查indexId参数
400Unable to process JSONbody格式不正确,请用 json检查器 检查格式

创建或更新单个对象


如果需要创建一个对象并令其使用指定的 ID,请使用本端点。

同时,如果指定的 ID 已经存在于引擎中,则本端点会更新对应的对象。因此,本端点也适用于更新单个对象。

PUT
https://api.kalasearch.cn/v1/indexes/{indexId}/{objectId}

请求参数

参数描述说明
JSON 格式的数据单个 JSON 格式的对象

请求示例

curl --location --request PUT 'https://api.kalasearch.cn/v1/indexes/501f6a76-c5f1-4e88-874c-dd33cd11c704/objects/id-001' \
--header 'X-Kalasearch-Id: 114a68ad-f8cb-485c-9ca3-e8f8692f5966' \
--header 'X-Kalasearch-Key: 44e763bc-0c61-4716-a5c7-0a77c3a96b11' \
--header 'Content-Type: application/json' \
--data-raw '{
"name": "大话西游",
"actors": "周星驰/吴孟达",
"year": 1998
}'

返回示例 200

{
"jobId": "6e467cac-aaaa-400d-995d-486a311a2bd5",
"jobStatus": "PENDING",
"objectId": "id-001"
}
返回项描述说明
jobId提交的任务 id如需查询任务状态需要用到这个 id
jobStatus任务运行状态,刚提交或运行中的任务为 PENDING
objectId为对象生成的 id

请注意,这里返回成功是指成功提交了一个添加对象的后台任务。具体的任务完成需要一定的时间,取决于队列中的任务量,通常在数秒到数十秒内完成。

如果需要查询提交的任务完成状态,请用查询任务状态端点。

错误信息

HTTP状态码返回消息(message)说明
404index does not exist索引不存在,请检查indexId参数
400Unable to process JSONbody格式不正确,请用 json检查器 检查格式

删除单个对象


如果需要删除一个对象,可以使用本端点

API端点

DELETE
https://api.kalasearch.cn/v1/indexes/{indexId}/objects/{objectId}

这里的 indexId 是你希望删除对象所在的索引 id,objectId 是你希望删除的对象 id。

如果在这个索引中 objectId 对应的对象存在,那么这个对象将被删除。如果在这个索引中,对应的 objectId 不存在,引擎仍然会认为这次删除请求成功。

请求示例

curl --location --request DELETE 'https://api.kalasearch.cn/v1/indexes/501f6a76-c5f1-4e88-874c-dd33cd11c704/objects/id-001' \
--header 'X-Kalasearch-Id: 114a68ad-f8cb-485c-9ca3-e8f8692f5966' \
--header 'X-Kalasearch-Key: 44e763bc-0c61-4716-a5c7-0a77c3a96b11'

返回示例 200

{
"jobId": "d1a5ca9c-e14d-4b26-bd5c-7f72365dfd8a",
"jobStatus": "PENDING",
"objectId": "id-001"
}
返回项描述说明
jobId提交的任务 id如需查询任务状态需要用到这个 id
jobStatus任务运行状态,刚提交或运行中的任务为 PENDING
objectId为对象生成的 id

请注意,这里返回成功是指成功提交了一个添加对象的后台任务。具体的任务完成需要一定的时间,取决于队列中的任务量,通常在数秒到数十秒内完成。

如果需要查询提交的任务完成状态,请用查询任务状态端点。

错误信息

HTTP状态码返回消息(message)说明
404index does not exist索引不存在,请检查indexId参数

搜索对象


在你向索引添加了一些对象之后,即可开始进行搜索。对于绝大多数应用来说,搜索操作远多于索引操作和添加对象操作。

API端点

POST
https://api.kalasearch.cn/v1/indexes/{indexId}/query

请注意,这里的indexId是你希望查询的索引的id,可以通过卡拉后台获得。

参数

参数描述说明
query搜索词用于搜索的搜索词,如 大话

query 是搜索最基本的参数,如果需要使用过滤器、翻页等功能,请参考搜索参数

示例

curl --location --request POST 'https://api.kalasearch.cn/v1/indexes/2bd1fe90-4bc6-41ec-b04d-7f52a757d14a/query' \
--header 'X-Kalasearch-Id: 981b9401-82fb-4efb-b5e4-c123ceac38da' \
--header 'X-Kalasearch-Key: 6a3125c5-67d6-4e28-8e28-7324f40a6acc' \
--header 'Content-Type: application/json' \
--data-raw '{
"query": "大话"
}'

返回

{
"totalHits": 1,
"hits": [
{
"objectId": "xa5e0HMBqHxfM3zkRJ84",
"source": {
"name": "大话西游",
"actors": "周星驰/吴孟达",
"year": 1998
}
}
],
"queryTimeUsed": 1
}
返回项描述说明
totalHits匹配的搜索结果总数
hits匹配的所有对象(array)hits 对象中的source为你添加对象时的JSON数据
queryTimeUsed匹配所用时间(毫秒)用于显示搜索速度

错误信息

HTTP状态码返回消息(message)说明
404index does not exist索引不存在,请检查indexId参数

搜索参数


除了最基本的字符串搜索以外,在搜索时还可以使用其它参数来丰富搜索功能。下列参数详细说明搜索时可以使用的参数和它们的默认值

filters - 过滤器

使用 filters 参数可以过滤搜索结果。比如说,如果你希望搜索含有”蓝牙“的手机,同时价格在 5000 元以下,则可以指定 price < 50000 这个 过滤器。

如果不指定 filters 的值,则其默认值为一个空字符串,即不进行任何过滤。详细的过滤器语法请参考:搜索结果过滤

示例:

{
"query": "大话",
"filters": "year > 1999 AND isGoodMovie:True"
}

page - 起始页

使用 page 起始页可以用来进行结果翻页。比如说,如果你的界面每页显示 10 个结果,用户在看完后希望翻到下一页,则可以用本参数来实现翻页。

如果不指定 page 的值,其默认值为 0,即结果的第一页。详见 排序和结果

示例:

{
"query": "大话",
"page": 2
}

hitsPerPage - 每页数量

使用 hitsPerPage 可以调整每页返回的结果数量,如果不指定,默认为 10。如果你指定一个更大的数字,比如 20,则引擎会每页返回对应数量的结果。详见 排序和结果

示例:

{
"query": "大话",
"page": 1,
"hitsPerPage": 20
}

查询任务状态


如果你提交了一个批量添加对象的任务,可以调用以下端点查询任务状态

API端点

GET
https://api.kalasearch.cn/v1/indexes/{indexId}/jobs/{jobId}

这里的 indexId 是你希望更新对象所在的索引 id,jobId 是提交任务时返回给你的 id

请求示例

curl --location --request GET 'https://api.kalasearch.cn/v1/indexes/ca7269b4-9c6e-4b33-9cfc-54376987a15d/jobs/429ddbc3-76ee-41c3-9110-4747a55497ee' \
--header 'X-Kalasearch-Id: 355f7ac7-5449-4ade-b4a6-1d5aeaed4143' \
--header 'X-Kalasearch-Key: 5aeac200-4270-429a-b0b8-ef3a823f78ab'

返回示例 200

{
"jobId": "71187459-acb5-4d8b-91d6-2610bbdb31cd",
"jobStatus": "COMPLETED",
"objectIds": [
"vPoRJ3YBESLUziTkxB43",
"vfoRJ3YBESLUziTkxB44"
]
}
返回项描述说明
jobId提交的任务 id
jobStatus可能值为 PENDINGCOMPLETED,前者表示任务在排队或进行中,后者表示任务已完成
objectIds数组,代表对应操作的对象 ID

任务执行结果保留在服务器一个小时。对绝大多数任务来说,只要提交时无报错,就可以保证执行正常,因此多数情况查询任务状态仅用于将异步(async)提交操作转为同步提交操作(sync)

支持数据类型


卡拉搜索所有的 API 端点均接收并返回 JSON 格式的数据。

对于要上传的 JSON 对象来说,暂时不支持嵌套 JSON 和数组类型,以下几种为目前支持的域

  • string: 字符串类型
  • number: 数字类型
  • boolean: 布尔类型

支持的 JSON 对象示例

{
"name": "无间道", // 字符串 - 支持
"actors": "刘德华", // 字符串 - 支持
"year": 2000, // 整数型数字 - 支持
"rating": 9.8, // 浮点类型 - 支持
"isGoodMovie": true // 布尔型 - 支持
}

暂不支持的 JSON 数据类型

{
"name": "张三",
"child": { // 嵌套 JSON 暂时不支持
"name": "张小三"
},
"education": [ // 数组类型暂时不支持
"长江一小",
"贵阳一中"
]
}
友情链接更新日志© 2021, 卡拉搜索, Built with ❤️ in San Francisco + Beijing

京ICP备15049164号-3