Merge pull request #833 from AnthonyTsu1984/restful-api

Restful api
milvus-io · Aug 23, 2023 · a6eb0f0 · a6eb0f0
2 parents c716b0f + dfde98d
commit a6eb0f0
Show file tree

Hide file tree

Showing 158 changed files with 12,930 additions and 3 deletions.
diff --git a/API_Reference/milvus-restful/v2.3.x/About.md b/API_Reference/milvus-restful/v2.3.x/About.md
@@ -0,0 +1,23 @@
+# Get Started
+
+Milvus offers RESTful API for you to manipulate your collections and data stored in them. Before you dive in, there are several things that are worth noting:
+
+## Understanding the API endpoints
+
+These API endpoints involve manipulating collections in a specified cluster as well as the data in a specific collection.
+
+The prefix of an API endpoint should always be the URI of your Milvus instance, such as `localhost:19530`.
+
+The following is the API endpoint used to list collections in a Milvus cluster.
+
+```shell
+curl --request GET \
+    --url '${MILVUS_HOST}:${MILVUS_PORT}/v1/vector/collections' \
+    --header 'Authorization: Bearer <TOKEN>' \
+    --header 'accept: application/json' \
+    --header 'content-type: application/json'
+```
+
+## Authentication credentials
+
+You can use a token as the authentication method when you access the API endpoints. To obtain a token, you should use a colon (:) to concatenate the username and password that you use to access your Milvus instance. For example, `root:milvus`.
diff --git a/API_Reference/milvus-restful/v2.3.x/Collection Operations/create_collection.md b/API_Reference/milvus-restful/v2.3.x/Collection Operations/create_collection.md
@@ -0,0 +1,118 @@
+# Create Collection
+
+Creates a collection in a cluster.
+
+<div>
+    <div style="display: inline-block; background: #026aca; font-size: 0.6em; border-radius: 10px; color: #ffffff; padding: 0.3em 1em;">
+        <span>POST</span>
+    </div>
+    <span style="font-weight: bold;">  https://${MILVUS_HOST}:${MILVUS_PORT}/v1/vector/collections/create</span>
+</div>
+
+## Example
+
+
+Create a collection named `medium_articles`:
+
+```shell
+curl --request POST \
+     --url "${MILVUS_HOST}:${MILVUS_PORT}/v1/vector/collections/create" \
+     --header "Authorization: Bearer ${TOKEN}" \
+     --header "accept: application/json" \
+     --header "content-type: application/json" \
+     -d '{
+       "dbName": "default",   
+       "collectionName": "medium_articles",
+       "dimension": 256,
+       "metricType": "L2",
+       "primaryField": "id",
+       "vectorField": "vector"
+      }'
+```
+
+Success response:
+
+```shell
+{
+    "code": 200,
+    "data": {}
+}
+```
+
+
+
+## Request
+
+### Parameters
+
+- No query parameters required
+
+- No path parameters required
+
+### Request Body
+
+```json
+{
+    "collectionName": "string",
+    "dbName": "string",
+    "description": "string",
+    "dimension": "integer",
+    "metricType": "string",
+    "primaryField": "string",
+    "vectorField": "string"
+}
+```
+
+| Parameter        | Description                                                                               |
+|------------------|-------------------------------------------------------------------------------------------|
+| `dbName`  | **string**<br>The name of the database to which the collection to create belongs to. |
+| `collectionName`  | **string**(required)<br>The name of the collection to create.|
+| `dimension`  | **integer**(required)<br>The number of dimensions for the vector field of the collection.<br>The value ranges from **32** to **32768**.|
+| `metricType`  | **string**<br>The distance metric used for the collection.<br>The value defaults to **L2**.|
+| `primaryField`  | **string**<br>The primary key field.<br>The value defaults to **id**.|
+| `vectorField`  | **string**<br>The vector field.<br>The value defaults to **vector**.|
+| `description`  | **string**<br>The description of the collection|
+
+## Response
+
+Returns an empty object.
+
+### Response Bodies
+
+- Response body if we process your request successfully
+
+```json
+{
+    "code": 200,
+    "data": {}
+}
+```
+
+- Response body if we failed to process your request
+
+```json
+{
+    "code": integer,
+    "message": string
+}
+```
+
+### Properties
+
+The properties in the returned response are listed in the following table.
+
+| Property | Description                                                                                                                                 |
+|----------|---------------------------------------------------------------------------------------------------------------------------------------------|
+| `code`   | **integer**<br>Indicates whether the request succeeds.<br><ul><li>`200`: The request succeeds.</li><li>Others: Some error occurs.</li></ul> |
+| `data`    | **object**<br>A data object. |
+| `message`  | **string**<br>Indicates the possible reason for the reported error. |
+
+## Possible Errors
+
+| Error Code | Description |
+| --- | --- |
+| 800 | database not found |
+| 1800 | user hasn't authenticate |
+| 1801 | can only accept json format request |
+| 1802 | missing required parameters |
+| 1803 | fail to marshal collection schema |
diff --git a/API_Reference/milvus-restful/v2.3.x/Collection Operations/describe_collection.md b/API_Reference/milvus-restful/v2.3.x/Collection Operations/describe_collection.md
@@ -0,0 +1,151 @@
+# Describe Collection
+
+Describes the details of a collection.
+
+<div>
+    <div style="display: inline-block; background: #0d8d67; font-size: 0.6em; border-radius: 10px; color: #ffffff; padding: 0.3em 1em;">
+        <span>GET</span>
+    </div>
+    <span style="font-weight: bold;">  https://${MILVUS_HOST}:${MILVUS_PORT}/v1/vector/collections/describe</span>
+</div>
+
+## Example
+
+
+Describe the details of a collection named `medium_articles`:
+
+```shell
+curl --request GET \
+     --url "${MILVUS_HOST}:${MILVUS_PORT}/v1/vector/collections/describe?collectionName=medium_articles" \
+     --header "Authorization: Bearer ${TOKEN}" \
+     --header "accept: application/json" \
+     --header "content-type: application/json"
+```
+
+Success response:
+
+```shell
+{
+    "code": 200,
+    "data": {
+        "collectionName": "string",
+        "description": "string",
+        "fields": [
+            {
+                "autoId": true,
+                "description": "string",
+                "name": "string",
+                "primaryKey": true,
+                "type": "string"
+            }
+        ],
+        "indexes": [
+            {
+                "fieldName": "string",
+                "indexName": "string",
+                "metricType": "string"
+            }
+        ],
+        "load": "string",
+        "shardsNum": 0,
+        "enableDynamicField": true
+    }
+}
+```
+
+
+
+## Request
+
+### Parameters
+
+- Query parameters
+
+    | Parameter        | Description                                                                               |
+    |------------------|-------------------------------------------------------------------------------------------|
+    | `collectionName`  | **string**(required)<br>The name of the collection to describe.|
+
+- No path parameters required
+
+### Request Body
+
+No request body required
+
+## Response
+
+Returns the specified collection in detail.
+
+### Response Bodies
+
+- Response body if we process your request successfully
+
+```json
+{
+    "code": 200,
+    "data": {
+        "collectionName": "string",
+        "description": "string",
+        "enableDynamicField": "boolean",
+        "fields": [
+            {
+                "autoId": "boolean",
+                "description": "string",
+                "name": "string",
+                "primaryKey": "boolean",
+                "type": "string"
+            }
+        ],
+        "indexes": [
+            {
+                "fieldName": "string",
+                "indexName": "string",
+                "metricType": "string"
+            }
+        ],
+        "load": "string",
+        "shardsNum": "integer"
+    }
+}
+```
+
+- Response body if we failed to process your request
+
+```json
+{
+    "code": integer,
+    "message": string
+}
+```
+
+### Properties
+
+The properties in the returned response are listed in the following table.
+
+| Property | Description                                                                                                                                 |
+|----------|---------------------------------------------------------------------------------------------------------------------------------------------|
+| `code`   | **integer**<br>Indicates whether the request succeeds.<br><ul><li>`200`: The request succeeds.</li><li>Others: Some error occurs.</li></ul> |
+| `data`    | **object**<br>A data object. |
+| `data.collectionName`   | **string**<br>The name of the collection. |
+| `data.description`   | **string**<br>An optional description of the collection. |
+| `data.fields`   | **array**<br>An field array |
+| `data.fields[].autoId`   | **boolean**<br>Whether the primary key automatically increments. |
+| `data.fields[].description`   | **string**<br>An optional description of the field. |
+| `data.fields[].name`   | **string**<br>The name of the field. |
+| `data.fields[].primaryKey`   | **boolean**<br>Whether the field is a primary field. |
+| `data.fields[].type`   | **string**<br>The data type of the values in this field. |
+| `data.indexes`   | **array**<br>An index array |
+| `data.indexes[].fieldName`   | **string**<br>The name of the indexed field. |
+| `data.indexes[].indexName`   | **string**<br>The name of the generated index files. |
+| `data.indexes[].metricType`   | **string**<br>The metric type used in the index process. |
+| `data.load`   | **string**<br>The load status of the collection. Possible values are **unload**, **loading**, and **loaded**. |
+| `data.shardsNum`   | **integer**<br>The number of shards in the collection. |
+| `data.enableDynamicField`   | **boolean**<br>Whether the dynamic JSON feature is enabled for this collection. |
+| `message`  | **string**<br>Indicates the possible reason for the reported error. |
+
+## Possible Errors
+
+| Error Code | Description |
+| --- | --- |
+| 800 | database not found |
+| 1800 | user hasn't authenticate |
+| 1802 | missing required parameters |
diff --git a/API_Reference/milvus-restful/v2.3.x/Collection Operations/drop_collection.md b/API_Reference/milvus-restful/v2.3.x/Collection Operations/drop_collection.md
@@ -0,0 +1,100 @@
+# Drop Collection
+
+Drops a collection. This operation erases your collection data. Exercise caution when performing this operation.
+
+<div>
+    <div style="display: inline-block; background: #026aca; font-size: 0.6em; border-radius: 10px; color: #ffffff; padding: 0.3em 1em;">
+        <span>POST</span>
+    </div>
+    <span style="font-weight: bold;">  https://${MILVUS_HOST}:${MILVUS_PORT}/v1/vector/collections/drop</span>
+</div>
+
+## Example
+
+
+Drop a collection named `medium_articles`:
+
+```shell
+curl --request POST \
+     --url "${MILVUS_HOST}:${MILVUS_PORT}/v1/vector/collections/drop" \
+     --header "Authorization: Bearer ${TOKEN}" \
+     --header "accept: application/json" \
+     --header "content-type: application/json" \
+     -d '{
+        "collectionName": "medium_articles"
+      }'
+```
+
+Success response:
+
+```shell
+{
+    "code": 200,
+    "data": {}
+}
+```
+
+
+
+## Request
+
+### Parameters
+
+- No query parameters required
+
+- No path parameters required
+
+### Request Body
+
+```json
+{
+    "collectionName": "string"
+}
+```
+
+| Parameter        | Description                                                                               |
+|------------------|-------------------------------------------------------------------------------------------|
+| `collectionName`  | **string**(required)<br>The name of the collection to delete.|
+
+## Response
+
+Returns an empty object.
+
+### Response Bodies
+
+- Response body if we process your request successfully
+
+```json
+{
+    "code": 200,
+    "data": {}
+}
+```
+
+- Response body if we failed to process your request
+
+```json
+{
+    "code": integer,
+    "message": string
+}
+```
+
+### Properties
+
+The properties in the returned response are listed in the following table.
+
+| Property | Description                                                                                                                                 |
+|----------|---------------------------------------------------------------------------------------------------------------------------------------------|
+| `code`   | **integer**<br>Indicates whether the request succeeds.<br><ul><li>`200`: The request succeeds.</li><li>Others: Some error occurs.</li></ul> |
+| `data`    | **object**<br>A data object. |
+| `message`  | **string**<br>Indicates the possible reason for the reported error. |
+
+## Possible Errors
+
+| Error Code | Description |
+| --- | --- |
+| 800 | database not found |
+| 1800 | user hasn't authenticate |
+| 1801 | can only accept json format request |
+| 1802 | missing required parameters |