Deploying Proxima on EAS

To get the Proxima version, send the following service request.

• Request:

  HTTP 1.1 GET /service_version

• Response:

  • status: The execution status of the Proxima server. For details, see Appendix: Common data types.

  • version: The release version, returned as a string.

• Request example:

  # Example: Get the version of Proxima SE
  ##################################################
  # Request:
  curl -X GET \
    http://144963168668****.cn-hongkong.pai-eas.aliyuncs.com/api/predict/proxima/service_version \
    -H 'cache-control: no-cache' \
    -H 'Authorization:${YourToken}' \
  ##################################################
  # Response:
  {
      "status": {
          "code": 0,
          "reason": "Success"
      },
      "version": "0.1.0-50-g16af91e"
  }

  Where:

  • http://144963168668****.cn-hongkong.pai-eas.aliyuncs.com/api/predict/proxima: The service endpoint. Replace this with the endpoint of your target service.

  • ${YourToken}: Your authorization token. Replace this with the token found on your service's invocation information page.

Use RESTful APIs to manage collections, including creating, deleting, and describing them.

• Create collection

  • Request

    HTTP 1.1 POST /v1/collection/<name>

    Where <name> is a path parameter that specifies the name of the collection that you want to create. The name must be globally unique.

  • Request body

    Parameter	Description
    collection_name	Optional. The name of the collection. If omitted, it defaults to the value of the <name> path parameter. Type: STRING.
    max_docs_per_segment	Optional. The maximum number of documents per segment. Type: UINT64. Defaults to the system's maximum value.
    forward_column_params	The forward column list is of the List[ForwardColumnParam, ...] type. The ForwardColumnParam is configured as follows: column_name: The name of the index column. The data type is STRING. data_type: The forward column data type, which must be specified as a string. For more information, see Appendix: General Data Types.
    index_column_params	The index list is of the List[IndexColumnParam,...] type, where IndexColumnParam is configured as follows: column_name: The name of the index column. The data type is STRING. index_type: The name of the index type (STRING). The valid values are as follows: IT_PROXIMA_GRAPH_INDEX: Graph index. IT_INVERT_INDEX: inverted index. data_type: The data type of the index column. The value must be a string. For more information, see Appendix: General Data Types. dimension: The data dimension. The data type is UINT32. This parameter is valid only for vector columns. For more information, see Appendix: General Data Types. extra_params: A list of advanced parameters of the List[KeyValuePair,...] type, where KeyValuePair is configured as follows: key: The parameter name. Type: STRING. value: The value of the parameter. Data type: STRING.

  • Return value

    The Proxima execution status. For more information, see Appendix: Common Data Types.

  • Request example

    # Example: Create a collection with two index columns
    ##################################################
    # Request:
    curl -X POST \
      http://144963168668****.cn-hongkong.pai-eas.aliyuncs.com/api/predict/proxima/v1/collection/example \
      -H 'cache-control: no-cache' \
      -H 'content-type: application/json' \
      -H 'Authorization:${YourToken}' \
      -d '{
        "collection_name":"example",
        "forward_column_params":[
          {"column_name": "Name", "data_type":"DT_STRING"},
          {"column_name": "SerialNo", "data_type":"DT_INT32"}
        ],
        "index_column_params":[
            {
                "column_name":"ImageVector",
                "index_type":"IT_PROXIMA_GRAPH_INDEX",
                "data_type":"DT_VECTOR_FP32",
                "dimension":8,
                "extra_params":[
                    {
                        "key":"ef_search",
                        "value":"200"
                    }
                ]
            },
            {"column_name":"Id",
              "index_type":"IT_INVERT_INDEX",
              "data_type":"DT_STRING"
            }
        ]
    }'
    ##################################################
    # Response:
    {
        "code": 0,
        "reason": "Success"
    }

    Where:

    • http://144963168668****.cn-hongkong.pai-eas.aliyuncs.com/api/predict/proxima: The service endpoint. You must replace this URL with the endpoint of your target service.

    • ${YourToken}: The token from the target service's invocation information page.

• Describe collection

  • Request

    HTTP 1.1 GET /v1/collection/<name>

    Where <name> is a path parameter that specifies the name of the collection to query.

  • Return value

    Parameter	Description
    status	The service execution status. For more information, see Appendix: Common Data Types.
    collection	Details about the collection. This object contains the following fields: uuid: The ID of the collection, which is a globally unique string. status: The status code of the collection, which is a STRING, with the following valid values: CS_INITIALIZED: Indicates that the collection has been initialized. CS_SERVING: Indicates that the collection is providing services normally. CS_DROPPED: Indicates that the collection has been deleted. magic_number: The magic number of the collection. Data type: UINT64. This parameter is associated with an external system and can be ignored. config: The configuration of the collection. For more information, see the Create Collection API's Request Body.

  • Request example

    # Example: Describe Collection
    ##################################################
    # Request:
    curl -X GET \
      http://144963168668****.cn-hongkong.pai-eas.aliyuncs.com/api/predict/proxima/v1/collection/example \
      -H 'cache-control: no-cache' \
      -H 'Authorization:${YourToken}' \
    ##################################################
    # Response:
    {
        "status": {
            "code": 0,
            "reason": "Success"
        },
        "collection": {
            "uuid": "d918becac22e471db41d55050809****",
            "config": {
                "collection_name": "example",
                "forward_column_params": [
                    {
                        "column_name": "Name",
                        "data_type": "DT_STRING",
                        "extra_params": []
                    },
                    {
                        "column_name": "SerialNo",
                        "data_type": "DT_INT32",
                        "extra_params": []
                    }
                ],
                "index_column_params": [
                    {
                        "column_name": "ImageVector",
                        "data_type": "DT_VECTOR_FP32",
                        "dimension": 8,
                        "extra_params": [],
                        "index_type": "IT_PROXIMA_GRAPH_INDEX"
                    },
                    {
                        "column_name": "Id",
                        "data_type": "DT_STRING",
                        "dimension": 0,
                        "extra_params": [],
                        "index_type": "IT_INVERT_INDEX"
                    }
                ],
                "max_docs_per_segment": "1844674407370955****"
            },
            "status": "CS_SERVING",
            "magic_number": "0"
        }
    }

    • http://144963168668****.cn-hongkong.pai-eas.aliyuncs.com/api/predict/proxima: The service endpoint. Replace this with the endpoint URL of your target service.

    • ${YourToken}: The token for the target service, obtained from the service invocation information page.

• Collection statistics

  Retrieves collection statistics, such as the number of files, storage size, and document count.

  • Request

    HTTP 1.1 GET /v1/collection/<name>/stats

    Where <name> is a path parameter that must be replaced with the name of the collection for which you want to obtain statistics.

  • Return value

    Parameter	Description
    status	The Proxima execution status. For more information, see Appendix: Common Data Types.
    collection_stats	The collection statistics. This object contains the following fields: collection_name: The name of the collection. Data type: STRING. collection_path: The storage path of the collection. The data type is STRING. total_doc_count: The total count of documents in the collection. The data type is STRING. total_segment_count: The total number of segments in the collection. Data type: STRING. total_index_file_size: The total storage size of the collection (STRING). total_index_file_count: The total number of files in the collection. The data type is STRING. segment_stats: A list of segment statistics. In multi-segment mode, multiple results are returned. The results contain the following content. state: The status code of the segment. Data type: STRING. Possible values: SS_WRITING: The segment is being written to. max_lsn: The largest record number in the segment. The data type is STRING. min_lsn: The minimum record number in a segment. The data type is STRING. doc_count: The number of documents in a segment. The data type is STRING. max_doc_id: The maximum document ID in a segment. The data type is STRING. min_doc_id: The minimum document ID in the segment. The data type is STRING. segment_id: The segment ID. The data type is UINT32. segment_path: The storage path of a segment. Data type: STRING. max_timestamp: The maximum document timestamp in a segment. Data type: STRING. min_timestamp: The minimum timestamp of documents in a segment. The data type is STRING. index_file_size: The storage size of a segment. Data type: STRING. max_primary_key: The maximum primary key value of documents within a segment. The data type is STRING. min_primary_key: The minimum primary key value for documents in a segment. The data type is STRING. index_file_count: The number of files in a segment. The data type is UINT32.

  • Request example

    # Example: Stats Collection
    ##################################################
    # Request:
    curl -X GET \
      http://144963168668****.cn-hongkong.pai-eas.aliyuncs.com/api/predict/proxima/v1/collection/example/stats \
      -H 'Authorization:${YourToken}' \
      -H 'cache-control: no-cache'
    ##################################################
    # Response:
    {
        "status": {
            "code": 0,
            "reason": "Success"
        },
        "collection_stats": {
            "segment_stats": [
                {
                    "state": "SS_WRITING",
                    "max_lsn": "0",
                    "min_lsn": "4294967295",
                    "doc_count": "0",
                    "max_doc_id": "0",
                    "min_doc_id": "0",
                    "segment_id": 0,
                    "segment_path": "",
                    "max_timestamp": "0",
                    "min_timestamp": "4294967295",
                    "index_file_size": "3223552",
                    "max_primary_key": "0",
                    "min_primary_key": "4294967295",
                    "index_file_count": "3"
                }
            ],
            "collection_name": "example",
            "collection_path": "/home/example.gxx/workspace/test/r/indices/example",
            "total_doc_count": "0",
            "total_segment_count": "1",
            "total_index_file_size": "7913472",
            "total_index_file_count": "7"
        }
    }

    Where:

    • http://144963168668****.cn-hongkong.pai-eas.aliyuncs.com/api/predict/proxima: The service endpoint. You must replace this with the URL of your target service.

    • ${YourToken}: The token from the target service's invocation information page.

• List collections

  If you provide no request parameters, the API returns all collections by default.

  • Request

    HTTP 1.1 GET /v1/collections

  • Return value

    Parameter	Description
    status	The Proxima execution status. For more information, see Appendix: Common Data Types.
    collections	The list of returned collections.

  • Request example

    # Example: List Collections
    ##################################################
    # Request:
    curl -X GET \
      http://144963168668****.cn-hongkong.pai-eas.aliyuncs.com/api/predict/proxima/v1/collections \
      -H 'Authorization:${YourToken}' \
      -H 'cache-control: no-cache'
    ##################################################
    # Response:
    {
        "status": {
            "code": 0,
            "reason": "Success"
        },
        "collections": [
            {
                "uuid": "d918becac22e471db41d55050809****",
                "config": {
                    "collection_name": "example",
                    "index_column_params": [
                      {
                          "column_name": "ImageVector",
                          "data_type": "DT_VECTOR_FP32",
                          "dimension": 8,
                          "extra_params": [],
                          "index_type": "IT_PROXIMA_GRAPH_INDEX"
                      },
                      {
                          "column_name": "Id",
                          "data_type": "DT_STRING",
                          "dimension": 0,
                          "extra_params": [],
                          "index_type": "IT_INVERT_INDEX"
                      }
                    ],
                    "forward_column_params": [
                      {
                          "column_name": "Name",
                          "data_type": "DT_STRING",
                          "extra_params": []
                      },
                      {
                          "column_name": "SerialNo",
                          "data_type": "DT_INT32",
                          "extra_params": []
                      }
                    ],
                    "max_docs_per_segment": "1844674407370955****"
                },
                "status": "CS_SERVING",
                "magic_number": "0"
            },
            {
                "uuid": "620976bd0d6728bb5ad566912f45****",
                "config": {
                    "collection_name": "example3",
                    "index_column_params": [
                      {
                          "column_name": "ImageVector",
                          "data_type": "DT_VECTOR_FP32",
                          "dimension": 8,
                          "extra_params": [],
                          "index_type": "IT_PROXIMA_GRAPH_INDEX"
                      },
                      {
                          "column_name": "Id",
                          "data_type": "DT_STRING",
                          "dimension": 0,
                          "extra_params": [],
                          "index_type": "IT_INVERT_INDEX"
                      }
                    ],
                    "forward_column_params": [
                      {
                          "column_name": "Name",
                          "data_type": "DT_STRING",
                          "extra_params": []
                      },
                      {
                          "column_name": "SerialNo",
                          "data_type": "DT_INT32",
                          "extra_params": []
                      }
                    ],
                    "max_docs_per_segment": "1844674407370955****"
                },
                "status": "CS_SERVING",
                "magic_number": "0"
            }
        ]
    }

    Where:

    • http://144963168668****.cn-hongkong.pai-eas.aliyuncs.com/api/predict/proxima: This is the service endpoint. You must replace it with the URL of your target service.

    • ${YourToken}: Specifies the token for the invocation information page of the target service.

• Delete collection

  • Request

    HTTP 1.1 DELETE /v1/collection/<name>

    Where: <name> is a path parameter that you must replace with the actual collection name.

  • Return value

    The Proxima execution status. For more information, see Appendix: Common Data Types.

  • Request example

    # Example: Delete Collection
    ##################################################
    # Request:
    curl -X DELETE \
      http://144963168668****.cn-hongkong.pai-eas.aliyuncs.com/api/predict/proxima/v1/collection/example \
      -H 'Authorization:${YourToken}' \
      -H 'cache-control: no-cache'
    ##################################################
    # Response:
    {
        "code": 0,
        "reason": "Success"
    }

    Where:

    • http://144963168668****.cn-hongkong.pai-eas.aliyuncs.com/api/predict/proxima: This is the service endpoint. You must replace it with the endpoint of your target service.

    • ${YourToken}: The token from the information page for the target service call.

You can use the RESTful API to insert, delete, and update documents. The document write API is for testing only and does not guarantee data durability.

• To perform document operations, such as insertion, deletion, and updates, specify the operation_type for each item in the rows array.

  • Request

    HTTP 1.1 POST /v1/collection/<name>/index

    Where <name> is a path parameter that you must replace with the actual collection name.

  • Request body

    Parameter	Description
    request_id	Optional. The request ID, used to correlate with external requests. Type: STRING.
    collection_name	Optional. The name of the collection. Defaults to the path parameter. Type: STRING.
    row_meta	The collection metadata. Type: RowMeta. This object includes lists of forward columns and index columns. forward_column_params: A list of index column configurations. The data type is List[IndexColumnMeta]. The parameters for IndexColumnMeta are as follows: column_name: The name of the index column. The data type is STRING. data_type: The forward column data type. The value must be a string. For more information, see Appendix: General data types. index_column_metas: A list of index column configurations of the List[IndexColumnMeta] type. The parameters for IndexColumnMeta are as follows: column_name: The name of the index column. The data type is STRING. data_type: The data type of the index column. For more information, see Appendix: general data types. dimension: The dimension of the index column. This parameter is of the UINT32 type and applies only to vector columns. For more information, see Appendix: General Data Types. rows: A list of document data. For more information, see Appendix: General data types. magic_number: Optional. A magic number of the UINT64 type (a 64-bit unsigned integer represented as a string), used to associate with external systems.

  • Response

    The execution status. For more information, see Appendix: Common Data Types.

  • Request example

    # Example: Insert document into collection
    ##################################################
    # Request:
    curl -X POST \
      http://144963168668****.cn-hongkong.pai-eas.aliyuncs.com/api/predict/proxima/v1/collection/example/index \
      -H 'cache-control: no-cache' \
      -H 'Authorization:${YourToken}' \
      -H 'content-type: application/json' \
      -d '{"collection_name":"example",
          "row_meta": {
            "forward_column_metas":[
              {"column_name":"Name","data_type":"DT_STRING"},
              {"column_name":"SerialNo","data_type":"DT_INT32"},
            ],
            "index_column_metas": [{
              "column_name":"ImageVector",
              "data_type":"DT_VECTOR_FP32",
              "dimension":8},{
              "column_name":"Id",
              "data_type":"DT_STRING"}]
          },
          "rows":[
            {
              "primary_key":0,
              "operation_type":"OP_INSERT",
              "forward_column_values":{
                "values":[{"string_value":"item1"}, {"int32_value":1}]},
              "index_column_values":{
                "values":[{"string_value":"[0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8]"}, {"string_value":"111111"}]}
            },
            {
              "primary_key":1,
              "operation_type":"OP_INSERT",
              "forward_column_values":{
                "values":[{"string_value":"item2"}, {"int32_value":2}]},
              "index_column_values":{
                "values":[{"string_value":"[1.1, 1.2, 1.3, 1.4, 1.5, 1.6, 1.7, 1.8]"}, {"string_value":"222222"}]}
            },
            {
              "primary_key":2,
              "operation_type":"OP_INSERT",
              "forward_column_values":{
                "values":[{"string_value":"item3"}, {"int32_value":3}]},
              "index_column_values":{
                "values":[{"string_value":"[2.1, 2.2, 2.3, 2.4, 2.5, 2.6, 2.7, 2.8]"}, {"string_value":"333333"}]}
            },
            {
              "primary_key":3,
              "operation_type":"OP_INSERT",
              "forward_column_values":{
                "values":[{"string_value":"item4"}, {"int32_value":4}]},
              "index_column_values":{
                "values":[{"string_value":"[3.1, 3.2, 3.3, 3.4, 3.5, 3.6, 3.7, 3.8]"}, {"string_value":"444444"}]}
            }
          ]
        }'
    ##################################################
    # Response:
    {
        "code": 0,
        "reason": "Success"
    }

    In this example:

    • http://144963168668****.cn-hongkong.pai-eas.aliyuncs.com/api/predict/proxima: The service endpoint. Replace this with the endpoint URL of the target service.

    • ${YourToken}: The token from the invocation information page for the target service.

• Query with JSON index search

  • Request

    HTTP 1.1 POST /v1/collection/<name>/query

    where name is a path parameter that you must replace with the actual collection name.

  • Request body

    Parameter	Description
    collection_name	Optional. The name of the collection. Defaults to the path parameter. Type: STRING.
    debug_mode	Optional. Enables debug mode. Type: BOOL. Valid values: true: Enable debug mode. false: The default value. Disables debug mode. Important Enabling this option increases request latency. Do not use it in a production environment.
    knn_param	Optional. Parameters for k-nearest neighbor (k-NN) search. For more information, see the nearest neighbor search parameters in Appendix: Common Data Types.
    query_filter	Optional. The filter condition for the query. For more information, see the filter condition parameters in Appendix: Common Data Types.
    query_fields	Optional. A list of fields to return in the results. Type: Array of strings.
    topk	The number of nearest neighbors to return. Type: UINT32.

  • Response

    Parameter	Description
    status	The query's status. For more information, see Appendix: Common Data Types.
    results	A list of the returned documents.
    debug_info	A JSON-formatted string that contains debug information. Type: STRING.
    latency_us	The request latency in microseconds. Type: STRING.

  • Example 1: Query without a filter

    # Example: Execute a k-NN query
    ##################################################
    # Request:
    curl -X POST http://144963168668****.cn-hongkong.pai-eas.aliyuncs.com/api/predict/proxima/v1/collection/example/query \
      -H 'cache-control: no-cache' \
      -H 'Authorization:${YourToken}' \
      -H 'content-type: application/json' \
      -d '{
        "collection_name":"example",
        "debug_mode":true,
        "knn_param":{
            "column_name":"ImageVector",
            "matrix":"[[1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0], [1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0], [1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0], [1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0]]",
            "batch_count":4,
            "dimension":8,
            "data_type":"DT_VECTOR_FP32",
            "is_linear":false,
            "extra_params":[
                {
                    "key":"customize_param",
                    "value":"10"
                },
                {
                    "key":"customize_param2",
                    "value":"1"
                },
                {
                    "key":"customize_param3",
                    "value":"str"
                }
            ]
        },
        "topk":10
    }' | python -m json.tool
    ##################################################
    # Response:
    {
        "debug_info": "{\"query\":{\"latency\":286,\"prepare\":40,\"evaluate\":{\"execute\":168,\"latency\":232,\"merge_and_sort\":58},\"validate\":9},\"latency\":311,\"query_id\":27,\"after_process_query\":{\"latency\":0},\"before_process_query\":{\"latency\":10}}",
        "latency_us": "420",
        "results": [
            {
                "documents": [
                    {
                        "forward_column_values": [
                            {
                                "key": "Name",
                                "value": {
                                    "string_value": "item4"
                                }
                            },
                            {
                                "key": "SerialNo",
                                "value": {
                                    "int32_value": 4
                                }
                            }
                        ],
                        "primary_key": "3",
                        "score": 42.84
                    },
                    {
                        "forward_column_values": [
                            {
                                "key": "Name",
                                "value": {
                                    "string_value": "item3"
                                }
                            },
                            {
                                "key": "SerialNo",
                                "value": {
                                    "int32_value": 3
                                }
                            }
                        ],
                        "primary_key": "2",
                        "score": 67.64
                    },
                    {
                        "forward_column_values": [
                            {
                                "key": "Name",
                                "value": {
                                    "string_value": "item2"
                                }
                            },
                            {
                                "key": "SerialNo",
                                "value": {
                                    "int32_value": 2
                                }
                            }
                        ],
                        "primary_key": "1",
                        "score": 108.44
                    },
                    {
                        "forward_column_values": [
                            {
                                "key": "Name",
                                "value": {
                                    "string_value": "item1"
                                }
                            },
                            {
                                "key": "SerialNo",
                                "value": {
                                    "int32_value": 1
                                }
                            }
                        ],
                        "primary_key": "0",
                        "score": 165.24
                    }
                ]
            },
            {
                "documents": [
                    {
                        "forward_column_values": [
                            {
                                "key": "Name",
                                "value": {
                                    "string_value": "item4"
                                }
                            },
                            {
                                "key": "SerialNo",
                                "value": {
                                    "int32_value": 4
                                }
                            }
                        ],
                        "primary_key": "3",
                        "score": 42.84
                    },
                    {
                        "forward_column_values": [
                            {
                                "key": "Name",
                                "value": {
                                    "string_value": "item3"
                                }
                            },
                            {
                                "key": "SerialNo",
                                "value": {
                                    "int32_value": 3
                                }
                            }
                        ],
                        "primary_key": "2",
                        "score": 67.64
                    },
                    {
                        "forward_column_values": [
                            {
                                "key": "Name",
                                "value": {
                                    "string_value": "item2"
                                }
                            },
                            {
                                "key": "SerialNo",
                                "value": {
                                    "int32_value": 2
                                }
                            }
                        ],
                        "primary_key": "1",
                        "score": 108.44
                    },
                    {
                        "forward_column_values": [
                            {
                                "key": "Name",
                                "value": {
                                    "string_value": "item1"
                                }
                            },
                            {
                                "key": "SerialNo",
                                "value": {
                                    "int32_value": 1
                                }
                            }
                        ],
                        "primary_key": "0",
                        "score": 165.24
                    }
                ]
            },
            {
                "documents": [
                    {
                        "forward_column_values": [
                            {
                                "key": "Name",
                                "value": {
                                    "string_value": "item4"
                                }
                            },
                            {
                                "key": "SerialNo",
                                "value": {
                                    "int32_value": 4
                                }
                            }
                        ],
                        "primary_key": "3",
                        "score": 42.84
                    },
                    {
                        "forward_column_values": [
                            {
                                "key": "Name",
                                "value": {
                                    "string_value": "item3"
                                }
                            },
                            {
                                "key": "SerialNo",
                                "value": {
                                    "int32_value": 3
                                }
                            }
                        ],
                        "primary_key": "2",
                        "score": 67.64
                    },
                    {
                        "forward_column_values": [
                            {
                                "key": "Name",
                                "value": {
                                    "string_value": "item2"
                                }
                            },
                            {
                                "key": "SerialNo",
                                "value": {
                                    "int32_value": 2
                                }
                            }
                        ],
                        "primary_key": "1",
                        "score": 108.44
                    },
                    {
                        "forward_column_values": [
                            {
                                "key": "Name",
                                "value": {
                                    "string_value": "item1"
                                }
                            },
                            {
                                "key": "SerialNo",
                                "value": {
                                    "int32_value": 1
                                }
                            }
                        ],
                        "primary_key": "0",
                        "score": 165.24
                    }
                ]
            },
            {
                "documents": [
                    {
                        "forward_column_values": [
                            {
                                "key": "Name",
                                "value": {
                                    "string_value": "item4"
                                }
                            },
                            {
                                "key": "SerialNo",
                                "value": {
                                    "int32_value": 4
                                }
                            }
                        ],
                        "primary_key": "3",
                        "score": 42.84
                    },
                    {
                        "forward_column_values": [
                            {
                                "key": "Name",
                                "value": {
                                    "string_value": "item3"
                                }
                            },
                            {
                                "key": "SerialNo",
                                "value": {
                                    "int32_value": 3
                                }
                            }
                        ],
                        "primary_key": "2",
                        "score": 67.64
                    },
                    {
                        "forward_column_values": [
                            {
                                "key": "Name",
                                "value": {
                                    "string_value": "item2"
                                }
                            },
                            {
                                "key": "SerialNo",
                                "value": {
                                    "int32_value": 2
                                }
                            }
                        ],
                        "primary_key": "1",
                        "score": 108.44
                    },
                    {
                        "forward_column_values": [
                            {
                                "key": "Name",
                                "value": {
                                    "string_value": "item1"
                                }
                            },
                            {
                                "key": "SerialNo",
                                "value": {
                                    "int32_value": 1
                                }
                            }
                        ],
                        "primary_key": "0",
                        "score": 165.24
                    }
                ]
            }
        ],
        "status": {
            "code": 0,
            "reason": "Success"
        }
    }

    In this example:

    • http://144963168668****.cn-hongkong.pai-eas.aliyuncs.com/api/predict/proxima: The service endpoint. Replace this with the endpoint of your target service.

    • ${YourToken}: The token address from the invocation information page of the target service.

  • Example 2: Query with a filter

    # Example: Execute a query with a filter
    ##################################################
    # Request:
    curl -X POST http://144963168668****.cn-hongkong.pai-eas.aliyuncs.com/api/predict/proxima/v1/collection/example/query \
      -H 'cache-control: no-cache' \
      -H 'Authorization:${YourToken}' \
      -H 'content-type: application/json' \
      -d '{
        "collection_name":"example",
        "debug_mode":true,
        "knn_param":{
            "column_name":"ImageVector",
            "matrix":"[1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0]",
            "batch_count":1,
            "dimension":8,
            "data_type":"DT_VECTOR_FP32",
            "is_linear":false
        },
        "query_filter": {
          "filter_node": {
            "logic_type" : "OR",
            "expressions" : [
              {
                "column_name" : "Id",
                "rel_type" : "EQ",
                "value": {"string_value" : "111111"}
              },
              {
                "column_name" : "Id",
                "rel_type" : "EQ",
                "value": {"string_value" : "222222"}
              }
            ]
          }
        },
        "topk":10
    }' | python -m json.tool
    ##################################################
    # Response:
    {
        "debug_info": "{\"query\":{\"latency\":286,\"prepare\":40,\"evaluate\":{\"execute\":168,\"latency\":232,\"merge_and_sort\":58},\"validate\":9},\"latency\":311,\"query_id\":27,\"after_process_query\":{\"latency\":0},\"before_process_query\":{\"latency\":10}}",
        "latency_us": "420",
        "results": [
            {
                "documents": [
                    {
                        "forward_column_values": [
                            {
                                "key": "Name",
                                "value": {
                                    "string_value": "item2"
                                }
                            },
                            {
                                "key": "SerialNo",
                                "value": {
                                    "int32_value": 2
                                }
                            }
                        ],
                        "primary_key": "1",
                        "score": 108.44
                    },
                    {
                        "forward_column_values": [
                            {
                                "key": "Name",
                                "value": {
                                    "string_value": "item1"
                                }
                            },
                            {
                                "key": "SerialNo",
                                "value": {
                                    "int32_value": 1
                                }
                            }
                        ],
                        "primary_key": "0",
                        "score": 165.24
                    }
                ]
            }
        ],
        "status": {
            "code": 0,
            "reason": "Success"
        }
    }

    In this example:

    • http://144963168668****.cn-hongkong.pai-eas.aliyuncs.com/api/predict/proxima: This is the service endpoint, and you must replace it with the endpoint of your target service.

    • ${YourToken}: Replace this placeholder with the token from the target service invocation information page.

• Query with SQL

  • Request

    HTTP 1.1 POST /v1/collection/<name>/sql

    Where: <name> is a path parameter, and you must replace it with the actual collection name.

  • Request body

    Parameter	Description
    sql	The SQL query string. Type: STRING. For more information, see Appendix: Common Data Types.
    debug_mode	Optional. Enables debug mode. Type: BOOL. Valid values: true: Enable debug mode. false: Default. Disables debug mode. Important Enabling this option increases request latency. Do not use it in a production environment.

  • Response

    Parameter	Description
    status	The query's status. For more information, see Appendix: Common Data Types.
    results	A list of the returned documents.
    debug_info	A JSON-formatted string that contains debug information. Type: STRING.
    latency_us	The request latency in microseconds. Type: STRING.

  • Request example

    # Example: Execute an SQL query
    ##################################################
    # Request:
    curl -X POST http://144963168668****.cn-hongkong.pai-eas.aliyuncs.com/api/predict/proxima/v1/collection/example/sql \
      -H 'cache-control: no-cache' \
      -H 'Authorization:${YourToken}' \
      -H 'content-type: application/json' \
      -d '{
        "sql":"select * from example limit 10",
        "debug_mode":true,
    }' | python -m json.tool
    ##################################################
    # Response:
    {
        "debug_info": "{\"latency\":750,\"plan stage\":{\"latency\":19},\"parse stage\":{\"latency\":550},\"analyze stage\":{\"latency\":25},\"execution stage\":{\"latency\":86}}",
        "latency_us": "809",
        "results": [
            {
                "documents": [
                    {
                        "forward_column_values": [
                            {
                                "key": "Name",
                                "value": {
                                    "string_value": "item1"
                                }
                            },
                            {
                                "key": "SerialNo",
                                "value": {
                                    "int32_value": 1
                                }
                            }
                        ],
                        "primary_key": "0",
                        "score": 0
                    },
                    {
                        "forward_column_values": [
                            {
                                "key": "Name",
                                "value": {
                                    "string_value": "item2"
                                }
                            },
                            {
                                "key": "SerialNo",
                                "value": {
                                    "int32_value": 2
                                }
                            }
                        ],
                        "primary_key": "1",
                        "score": 0
                    },
                    {
                        "forward_column_values": [
                            {
                                "key": "Name",
                                "value": {
                                    "string_value": "item3"
                                }
                            },
                            {
                                "key": "SerialNo",
                                "value": {
                                    "int32_value": 3
                                }
                            }
                        ],
                        "primary_key": "2",
                        "score": 0
                    },
                    {
                        "forward_column_values": [
                            {
                                "key": "Name",
                                "value": {
                                    "string_value": "item4"
                                }
                            },
                            {
                                "key": "SerialNo",
                                "value": {
                                    "int32_value": 4
                                }
                            }
                        ],
                        "primary_key": "3",
                        "score": 0
                    }
                ]
            }
        ],
        "status": {
            "code": 0,
            "reason": "Success"
        }
    }

    In this example:

    • http://144963168668****.cn-hongkong.pai-eas.aliyuncs.com/api/predict/proxima: The service endpoint URL. You must replace this with the URL of your target service.

    • ${YourToken}: The token from the invocation information page of the target service.

• Query by primary key

  • Request

    HTTP 1.1 GET /v1/collection/{name}/doc?key=<key>

    Where: <key> is the primary key of the document. This parameter is of the UINT64 type and must be replaced with the actual primary key of the document.

  • Response

    Parameter	Description
    status	The query's status. For more information, see Appendix: Common Data Types.
    document	The returned document. For more information, see Appendix: Common Data Types.
    debug_info	A JSON-formatted string that contains debug information. Type: STRING.

  • Request example

    # Example: Query a document by primary key
    ##################################################
    # Request:
    curl -X GET \
      'http://144963168668****.cn-hongkong.pai-eas.aliyuncs.com/api/predict/proxima/v1/collection/example/doc?key=2' \
      -H 'Authorization:${YourToken}' \
      -H 'cache-control: no-cache'
    ##################################################
    # Response:
    {
        "status": {
            "code": 0,
            "reason": "Success"
        },
        "document": {
            "forward_column_values": [
                {
                    "key": "Name",
                    "value": {
                        "string_value": "item3"
                    }
                },
                {
                    "key": "SerialNo",
                    "value": {
                        "int32_value": 3
                    }
                }
            ],
            "primary_key": "2",
            "score": 0
        },
        "debug_info": ""
    }

    In this example:

    • http://144963168668****.cn-hongkong.pai-eas.aliyuncs.com/api/predict/proxima: The service endpoint for API calls, which you must replace with the endpoint of your target service.

    • ${YourToken}: The token for the target service. You can obtain this token from the service call information page.

Status

• code: The status code returned by the server. Type: INT32.

  • A value of 0 indicates successful execution.

  • A non-zero value indicates an execution error. In this case, the reason field contains specific error information.

• reason: Optional. Additional error information. Type: STRING.

ForwardDataTypes: Optional. Specifies the data type of the forward index. Type: STRING. Valid values:

• DT_INT8: 8-bit signed integer.

• DT_UINT8: 8-bit unsigned integer.

• DT_INT16: 16-bit signed integer.

• DT_UINT16: 16-bit unsigned integer.

• DT_INT32: 32-bit signed integer.

• DT_UINT32: 32-bit unsigned integer.

• DT_INT64: 64-bit signed integer.

• DT_UINT64: 64-bit unsigned integer.

• DT_FLOAT: 32-bit floating-point number.

• DT_DOUBLE: 64-bit floating-point number.

• DT_STRING: String.

Row

• primary_key: Optional. The primary key of the document. Type: UINT64.

• operation_type: The operation type. Type: STRING. Valid values:

  • OP_INSERT: Inserts the document.

  • OP_UPDATE: Updates the document with the specified primary_key.

  • OP_DELETE: Deletes the document with the specified primary_key.

• index_column_values: The vector column data.

  values: Valid values:

  • bytes_value: The vector data, Base64-encoded. Type: STRING.

  • string_value: The vector data in JSON string format. Type: STRING. Use either this parameter or bytes_value.

• forward_column_values: The forward column data.

  values: A list of forward column data. The key of each value object identifies its data type. Valid values:

  • bytes_value: Binary data, Base64-encoded. Type: STRING.

  • string_value: String data. Type: STRING.

  • bool_value: Boolean data. Type: BOOL. Valid values are TRUE or FALSE.

  • int32_value: A 32-bit signed integer. Type: INT32.

  • int64_value: A 64-bit signed integer. Type: STRING.

  • uint32_value: A 32-bit unsigned integer. Type: UINT32.

  • uint64_value: A 64-bit unsigned integer. Type: STRING.

  • float_value: A 32-bit floating-point number. Type: FLOAT.

  • double_value: A 64-bit floating-point number. Type: DOUBLE.

• lsn_context: Optional. Identifies the unique source of a document. Typically used for data synchronization.

Example 1: Base64-encoded vector data

{
    "index_column_values":{
        "values":[
            {
                "bytes_value":"P4AAAEAAAABAQAAAQIAAAECgAABAwAAAQOAAAEEAAAA="
            }
        ]
    },
    "forward_column_values":{
        "values":[
            {
                "int64_value":"1"
            },
            {
                "float_value":1.1
            }
        ]
    }
}

Example 2: Vector data in JSON string format

{
    "index_column_values":{
        "values":[
            {
                "string_value":"[1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0]"
            }
        ]
    },
    "forward_column_values":{
        "values":[
            {
                "int64_value":"1"
            },
            {
                "float_value":1.1
            }
        ]
    }
}

KnnQueryParam

• column_name: The name of the index column. Type: STRING.

• A list of query vectors. Specify one of the following parameters:

  • matrix: A list of query vectors in JSON format. Format: List[List[String]...].

  • features: One or more query vectors, Base64-encoded. For batch requests, concatenate the encoded vectors without separators. Type: STRING.

• batch_count: The number of vectors in a batch request. Type: UINT32.

• dimension: The vector dimension. Type: UINT32.

• data_type: For details, see Index column data types.

• radius: The search radius. The valid value range depends on the distance function used. Type: FLOAT.

• is_linear: Specifies whether to perform a linear search. Type: BOOL.

• extra_params: Additional search parameters. Type: Map[String, String]. Currently, only post_filter_topk is supported.

  post_filter_topk: Enables post-filtering and specifies the number of results to return after filtering. Type: UINT32.

Syntax

#SELECT:
SELECT { * | columnName ["," columnName ]* } FROM CollectionName [ WHERE FilterExpression ] [ ORDER BY columnName [DESC] ] [ LIMIT number]

Statement structure:

• columnName: Identifier.

• FilterExpression: LogicExpr.

• LogicExpr: LogicExpr AND LogicExpr | LogicExpr OR LogicExpr | "(" LogicExpr ")" | RelationExpr.

• RelationExpr: columnName {"=" | "!=" | ">" | ">=" | "<" | "<=" | "LIKE"} ValueExpr.

• ValueExpr: Numeric | String | TRUE | FALSE | Vector | Matrix | Function.

• Vector: "[" Numeric ["," Numeric ]* "]".

• Matrix: "[" Vector ["," Vector ]* "]".

• Numeric: int_value | float_value.

• String: "'" character [character]* "'".

• Function: FuncName "(" param [, param ]* ")".

• FuncName: Identifier.

Limitations

• The ORDER BY clause currently supports only a single column.

• Filter conditions are supported for all types except BINARY. LIKE is used for STRING comparisons.

• Currently, only the feature function is supported. Its parameters are as follows:

  • vector or matrix: The vector value.

  • data_type: Optional. The type of the vector value.

  • dimension: Optional. The vector dimension.

  • Extended fields: Optional. A string of key-value pairs in the format key=value, separated by semicolons (;). The supported keys are:

    • radius: Optional. The search radius.

    • is_linear: Optional. Specifies whether to perform a linear search.

Examples

• Query all documents

  select * from Plants;

• Query specified fields

  select Price, Description from Plants;

• Query by vector condition

  select * from Plants where ImageVector=[1.1, 1.2, 1.3, 1.4, 1.5, 1.6, 1.7, 1.8];

• Query by multiple vector conditions

  select * from Plants where ImageVector=[[1.1, 1.2, 1.3, 1.4, 1.5, 1.6, 1.7, 1.8],[1.1, 1.2, 1.3, 1.4, 1.5, 1.6, 1.7, 1.8]]; 

• Query by forward index condition

  select * from Plants where Price=1.1 or Price=2.1;

  In this query, Price is a forward index.

• Query by inverted index condition

  select * from Plants where Name='item1';

  In this query, Name is an inverted index.

• Combine inverted index and forward index conditions

  select * from Plants where Name='item1' and (Price=1.1 or Price=2.1);

• Combine vector, inverted index, and forward index conditions with sorting and a limit

  select Price from Plants where ImageVector=[1.1, 1.2, 1.3, 1.4, 1.5, 1.6, 1.7, 1.8] and Name='item1' and (Price=1.1 or Price=2.1) order by Price limit 10;

• Use the vector feature function

  select Price from Plants where ImageVector=feature([1.1, 1.2, 1.3, 1.4, 1.5, 1.6, 1.7, 1.8], 'VECTOR_FP32', 8, 'radius=0.1;is_linear=false');

• Use the multi-vector feature function

  select Price from Plants where ImageVector=feature([[1.1, 1.2, 1.3, 1.4, 1.5, 1.6, 1.7, 1.8],[1.1, 1.2, 1.3, 1.4, 1.5, 1.6, 1.7, 1.8]], 'VECTOR_FP32', 8, 'radius=0.1;is_linear=false');

  ageVect

Vector, forward index, and inverted index query conditions can be combined using AND or OR. However, all search conditions must match one of the following patterns:

• A single condition (vector, inverted index, or forward index).

• Multiple conditions that adhere to the following rules:

  • At most one vector condition is allowed, and it cannot be part of an OR clause.

  • If no vector condition is present, at most one inverted index condition is allowed, and it cannot be part of an OR clause. If a vector condition exists, multiple inverted index conditions are allowed, provided they follow these rules:

    All inverted index conditions must belong to a single subtree (which does not have to be the top-level subtree). This subtree must contain only inverted index conditions and cannot be mixed with vector or forward index conditions. The subtree as a whole cannot be an operand of an OR operator, but it can contain OR operators internally.

For example, assume Feature is a vector column, A through Z are inverted index columns, and a through z are forward index columns.

• Feature=[]

  Valid.

• Feature=[] and Feature2=[]

  Invalid. Contains multiple vector columns.

• Feature=[] and A=1 and B=2 and C=3

  Valid. All inverted index conditions are in a single subtree. The first AND acts as the root, dividing the expression into two subtrees. The right subtree contains only inverted index conditions.

• Feature=[] and A=1 and B=2 or C=3

  Invalid. Because OR has a lower precedence, it splits this expression into two subtrees, and the inverted index conditions exist in multiple subtrees.

• A=1 and B=2 and C=3 and Feature=[]

  Invalid. The first AND acts as the root, creating two subtrees. The right subtree contains both inverted index conditions and a non-inverted-index condition (the vector condition).

• (A=1 and B=2 or C=3) and Feature=[]

  Valid. All inverted index conditions are in a single subtree, and the subtree can contain an OR operator internally.

• Feature=[] and (A=1 and B=2 or C=3) and a=1

  Valid. All inverted index conditions are in a single subtree.

• Feature=[] and (A=1 and B=2 or C=3) and a=1 and D=4

  Invalid. The inverted index conditions exist in multiple subtrees. Here, (A=1 and B=2 or C=3) and D=4 are in different subtrees. If you consider all inverted index conditions to be in the top-level right subtree, that subtree also contains a=1, which is not an inverted index condition.

• a=1 and Feature=[] and b=2 and (A=1 and B=2 or C=3) and c=3

  Valid. The parentheses ensure that (A=1 and B=2 or C=3) exists in its own subtree, which can contain an OR operator internally.

• a=1 and Feature=[] and (b=2 or (A=1 and B=2 or C=3) and c=3)

  Invalid. The subtree containing inverted index conditions cannot be an operand of an OR operator. Here, (A=1 and B=2 or C=3) is part of a larger OR expression.

Documents

• score: The relevance score. Type: FLOAT.

• primary_key: A 64-bit unsigned integer. Type: STRING.

• forward_column_values: A list of Property objects. Type: List[Property,...].

Property

• key: The property name. Type: STRING.

• value: The property value. The data type is variable.