MilvusClient.java 13 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422
  1. /*
  2. * Licensed to the Apache Software Foundation (ASF) under one
  3. * or more contributor license agreements. See the NOTICE file
  4. * distributed with this work for additional information
  5. * regarding copyright ownership. The ASF licenses this file
  6. * to you under the Apache License, Version 2.0 (the
  7. * "License"); you may not use this file except in compliance
  8. * with the License. You may obtain a copy of the License at
  9. *
  10. * http://www.apache.org/licenses/LICENSE-2.0
  11. *
  12. * Unless required by applicable law or agreed to in writing,
  13. * software distributed under the License is distributed on an
  14. * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
  15. * KIND, either express or implied. See the License for the
  16. * specific language governing permissions and limitations
  17. * under the License.
  18. */
  19. package io.milvus.client;
  20. import com.google.common.util.concurrent.ListenableFuture;
  21. import java.util.List;
  22. /** The Milvus Client Interface */
  23. public interface MilvusClient {
  24. String clientVersion = "0.7.0";
  25. /** @return current Milvus client version: 0.7.0 */
  26. default String getClientVersion() {
  27. return clientVersion;
  28. }
  29. /**
  30. * Connects to Milvus server
  31. *
  32. * @param connectParam the <code>ConnectParam</code> object
  33. * <pre>
  34. * example usage:
  35. * <code>
  36. * ConnectParam connectParam = new ConnectParam.Builder()
  37. * .withHost("localhost")
  38. * .withPort(19530)
  39. * .withConnectTimeout(10, TimeUnit.SECONDS)
  40. * .withKeepAliveTime(Long.MAX_VALUE, TimeUnit.NANOSECONDS)
  41. * .withKeepAliveTimeout(20, TimeUnit.SECONDS)
  42. * .keepAliveWithoutCalls(false)
  43. * .withIdleTimeout(24, TimeUnit.HOURS)
  44. * .build();
  45. * </code>
  46. * </pre>
  47. *
  48. * @return <code>Response</code>
  49. * @throws ConnectFailedException if client failed to connect
  50. * @see ConnectParam
  51. * @see Response
  52. * @see ConnectFailedException
  53. */
  54. Response connect(ConnectParam connectParam) throws ConnectFailedException;
  55. /**
  56. * @return <code>true</code> if the client is connected to Milvus server and the channel's
  57. * connectivity state is READY.
  58. */
  59. boolean isConnected();
  60. /**
  61. * Disconnects from Milvus server
  62. *
  63. * @return <code>Response</code>
  64. * @throws InterruptedException
  65. * @see Response
  66. */
  67. Response disconnect() throws InterruptedException;
  68. /**
  69. * Creates collection specified by <code>collectionMapping</code>
  70. *
  71. * @param collectionMapping the <code>CollectionMapping</code> object
  72. * <pre>
  73. * example usage:
  74. * <code>
  75. * CollectionMapping collectionMapping = new CollectionMapping.Builder(collectionName, dimension)
  76. * .withIndexFileSize(1024)
  77. * .withMetricType(MetricType.IP)
  78. * .build();
  79. * </code>
  80. * </pre>
  81. *
  82. * @return <code>Response</code>
  83. * @see CollectionMapping
  84. * @see MetricType
  85. * @see Response
  86. */
  87. Response createCollection(CollectionMapping collectionMapping);
  88. /**
  89. * Checks whether the collection exists
  90. *
  91. * @param collectionName collection to check
  92. * @return <code>HasCollectionResponse</code>
  93. * @see HasCollectionResponse
  94. * @see Response
  95. */
  96. HasCollectionResponse hasCollection(String collectionName);
  97. /**
  98. * Drops collection
  99. *
  100. * @param collectionName collection to drop
  101. * @return <code>Response</code>
  102. * @see Response
  103. */
  104. Response dropCollection(String collectionName);
  105. /**
  106. * Creates index specified by <code>index</code>
  107. *
  108. * @param index the <code>Index</code> object
  109. * <pre>
  110. * example usage:
  111. * <code>
  112. * Index index = new Index.Builder(collectionName, IndexType.IVF_SQ8)
  113. * .withParamsInJson("{\"nlist\": 16384}")
  114. * .build();
  115. * </code>
  116. * </pre>
  117. *
  118. * @return <code>Response</code>
  119. * @see Index
  120. * @see IndexType
  121. * @see Response
  122. */
  123. Response createIndex(Index index);
  124. /**
  125. * Creates a partition specified by <code>collectionName</code> and <code>tag</code>
  126. *
  127. * @param collectionName collection name
  128. * @param tag partition tag
  129. * @return <code>Response</code>
  130. * @see Response
  131. */
  132. Response createPartition(String collectionName, String tag);
  133. /**
  134. * Shows current partitions of a collection
  135. *
  136. * @param collectionName collection name
  137. * @return <code>ShowPartitionsResponse</code>
  138. * @see ShowPartitionsResponse
  139. * @see Response
  140. */
  141. ShowPartitionsResponse showPartitions(String collectionName);
  142. /**
  143. * Drops partition specified by <code>collectionName</code> and <code>tag</code>
  144. *
  145. * @param collectionName collection name
  146. * @param tag partition tag
  147. * @see Response
  148. */
  149. Response dropPartition(String collectionName, String tag);
  150. /**
  151. * Inserts data specified by <code>insertParam</code>
  152. *
  153. * @param insertParam the <code>InsertParam</code> object
  154. * <pre>
  155. * example usage:
  156. * <code>
  157. * InsertParam insertParam = new InsertParam.Builder(collectionName)
  158. * .withFloatVectors(floatVectors)
  159. * .withVectorIds(vectorIds)
  160. * .withPartitionTag(tag)
  161. * .build();
  162. * </code>
  163. * </pre>
  164. *
  165. * @return <code>InsertResponse</code>
  166. * @see InsertParam
  167. * @see InsertResponse
  168. * @see Response
  169. */
  170. InsertResponse insert(InsertParam insertParam);
  171. /**
  172. * Searches vectors specified by <code>searchParam</code>
  173. *
  174. * @param searchParam the <code>SearchParam</code> object
  175. * <pre>
  176. * example usage:
  177. * <code>
  178. * SearchParam searchParam = new SearchParam.Builder(collectionName)
  179. * .withFloatVectors(floatVectors)
  180. * .withTopK(topK)
  181. * .withPartitionTags(partitionTagsList)
  182. * .withParamsInJson("{\"nprobe\": 20}")
  183. * .build();
  184. * </code>
  185. * </pre>
  186. *
  187. * @return <code>SearchResponse</code>
  188. * @see SearchParam
  189. * @see SearchResponse
  190. * @see SearchResponse.QueryResult
  191. * @see Response
  192. */
  193. SearchResponse search(SearchParam searchParam);
  194. /**
  195. * Searches vectors specified by <code>searchParam</code> asynchronously
  196. *
  197. * @param searchParam the <code>SearchParam</code> object
  198. * <pre>
  199. * example usage:
  200. * <code>
  201. * SearchParam searchParam = new SearchParam.Builder(collectionName)
  202. * .withFloatVectors(floatVectors)
  203. * .withTopK(topK)
  204. * .withPartitionTags(partitionTagsList)
  205. * .withParamsInJson("{\"nprobe\": 20}")
  206. * .build();
  207. * </code>
  208. * </pre>
  209. *
  210. * @return a <code>ListenableFuture</code> object which holds the <code>SearchResponse</code>
  211. * @see SearchParam
  212. * @see SearchResponse
  213. * @see SearchResponse.QueryResult
  214. * @see Response
  215. * @see ListenableFuture
  216. */
  217. ListenableFuture<SearchResponse> searchAsync(SearchParam searchParam);
  218. /**
  219. * Searches vectors in specific files
  220. *
  221. * @param fileIds list of file ids to search from
  222. * @param searchParam the <code>SearchParam</code> object
  223. * <pre>
  224. * example usage:
  225. * <code>
  226. * SearchParam searchParam = new SearchParam.Builder(collectionName)
  227. * .withFloatVectors(floatVectors)
  228. * .withTopK(topK)
  229. * .withPartitionTags(partitionTagsList)
  230. * .withParamsInJson("{\"nprobe\": 20}")
  231. * .build();
  232. * </code>
  233. * </pre>
  234. *
  235. * @return <code>SearchResponse</code>
  236. * @see SearchParam
  237. * @see SearchResponse
  238. * @see SearchResponse.QueryResult
  239. * @see Response
  240. */
  241. SearchResponse searchInFiles(List<String> fileIds, SearchParam searchParam);
  242. /**
  243. * Describes the collection
  244. *
  245. * @param collectionName collection to describe
  246. * @see DescribeCollectionResponse
  247. * @see CollectionMapping
  248. * @see Response
  249. */
  250. DescribeCollectionResponse describeCollection(String collectionName);
  251. /**
  252. * Shows current collections
  253. *
  254. * @return <code>ShowCollectionsResponse</code>
  255. * @see ShowCollectionsResponse
  256. * @see Response
  257. */
  258. ShowCollectionsResponse showCollections();
  259. /**
  260. * Gets current row count of a collection
  261. *
  262. * @param collectionName collection to get row count
  263. * @return <code>GetCollectionRowCountResponse</code>
  264. * @see GetCollectionRowCountResponse
  265. * @see Response
  266. */
  267. GetCollectionRowCountResponse getCollectionRowCount(String collectionName);
  268. /**
  269. * Get server status
  270. *
  271. * @return <code>Response</code>
  272. * @see Response
  273. */
  274. Response getServerStatus();
  275. /**
  276. * Get server version
  277. *
  278. * @return <code>Response</code>
  279. * @see Response
  280. */
  281. Response getServerVersion();
  282. /**
  283. * Sends a command to server
  284. *
  285. * @return <code>Response</code> command's response will be return in <code>message</code>
  286. * @see Response
  287. */
  288. Response command(String command);
  289. /**
  290. * Pre-loads collection to memory
  291. *
  292. * @param collectionName collection to preload
  293. * @return <code>Response</code>
  294. * @see Response
  295. */
  296. Response preloadCollection(String collectionName);
  297. /**
  298. * Describes collection index
  299. *
  300. * @param collectionName collection to describe index of
  301. * @see DescribeIndexResponse
  302. * @see Index
  303. * @see Response
  304. */
  305. DescribeIndexResponse describeIndex(String collectionName);
  306. /**
  307. * Drops collection index
  308. *
  309. * @param collectionName collection to drop index of
  310. * @see Response
  311. */
  312. Response dropIndex(String collectionName);
  313. /**
  314. * Shows collection information. A collection consists of one or multiple partitions (including
  315. * the default partition), and a partitions consists of one or more segments. Each partition or
  316. * segment can be uniquely identified by its partition tag or segment name respectively.
  317. *
  318. * @param collectionName collection to show info from
  319. * @see ShowCollectionInfoResponse
  320. * @see CollectionInfo
  321. * @see CollectionInfo.PartitionInfo
  322. * @see CollectionInfo.PartitionInfo.SegmentInfo
  323. * @see Response
  324. */
  325. ShowCollectionInfoResponse showCollectionInfo(String collectionName);
  326. /**
  327. * Gets either a float or binary vector by id.
  328. *
  329. * @param collectionName collection to get vector from
  330. * @param id vector id
  331. * @see GetVectorByIdResponse
  332. * @see Response
  333. */
  334. GetVectorByIdResponse getVectorById(String collectionName, Long id);
  335. /**
  336. * Gets all vector ids in a segment
  337. *
  338. * @param collectionName collection to get vector ids from
  339. * @param segmentName segment name
  340. * @see GetVectorIdsResponse
  341. * @see Response
  342. */
  343. GetVectorIdsResponse getVectorIds(String collectionName, String segmentName);
  344. /**
  345. * Deletes data in a collection by a list of ids
  346. *
  347. * @param collectionName collection to delete ids from
  348. * @param ids a <code>List</code> of vector ids to delete
  349. * @see Response
  350. */
  351. Response deleteByIds(String collectionName, List<Long> ids);
  352. /**
  353. * Deletes data in a collection by a single id
  354. *
  355. * @param collectionName collection to delete id from
  356. * @param id vector id to delete
  357. * @see Response
  358. */
  359. Response deleteById(String collectionName, Long id);
  360. /**
  361. * Flushes data in a list collections. Newly inserted or modifications on data will be visible
  362. * after <code>flush</code> returned
  363. *
  364. * @param collectionNames a <code>List</code> of collections to flush
  365. * @see Response
  366. */
  367. Response flush(List<String> collectionNames);
  368. /**
  369. * Flushes data in a collection. Newly inserted or modifications on data will be visible after
  370. * <code>flush</code> returned
  371. *
  372. * @param collectionName name of collection to flush
  373. * @see Response
  374. */
  375. Response flush(String collectionName);
  376. /**
  377. * Compacts the collection, erasing deleted data from disk and rebuild index in background (if the
  378. * data size after compaction is still larger than indexFileSize). Data was only soft-deleted
  379. * until you call compact.
  380. *
  381. * @param collectionName name of collection to compact
  382. * @see Response
  383. */
  384. Response compact(String collectionName);
  385. }