TopicRank

Function

This API is used to run the TopicRank algorithm based on input parameters.

This algorithm is one of commonly used algorithms for ranking topics by multiple dimensions. For example, this algorithm is applicable to rank complaint topics obtained through a government hotline.

URI

POST /ges/v1.0/{project_id}/hyg/{graph_name}/algorithm

**Table 1** URI parameters
Parameter	Mandatory	Type	Description
project_id	Yes	String	Project ID. For how to obtain the project ID, see Obtaining a Project ID.
graph_name	Yes	String	Graph name

Request Parameters

**Table 2** Request body parameters
Parameter	Mandatory	Type	Description
algorithmName	Yes	String	Algorithm name
parameters	Yes	parameters Object	Algorithm parameters

**Table 3** parameters
Parameter	Mandatory	Type	Description
sources	Yes	String	Vertex ID. You can specify multiple node IDs in CSV format and separate them with commas (,). Currently, a maximum of 100000 IDs are allowed.
actived_p	No	Double	Initial weight of the start sources vertex. The value range is [0, 100000]. The default value is 1.
default_p	No	Double	Initial weight of a non-sources vertex. The value range is [0, 100000]. The default value is 1.
filtered	No	Boolean	Whether results are filtered. The options include true or false. The default value is false.
only_neighbors	No	Boolean	Whether only the neighboring vertices of sources are output. The value can be true or false. The default value is true.
alpha	No	Double	Weight coefficient (also called damping coefficient). The value range is (0, 1). The default value is 0.85.
convergence	No	Double	Convergence accuracy. The value range is (0, 1). The default value is 0.00001.
max_iterations	No	Integer	Maximum number of iterations. The value range is [0, 2000]. The default value is 1000.
directed	No	Boolean	Whether to consider the edge direction. The value can be true or false. The default value is true.
num_thread	No	Integer	Number of threads. The value ranges from 1 to the maximum number of CPU threads. The default value is 4.
vertex_filter	No	Json String	This parameter is optional when operator is set to inV, outV, or bothV. For details about the format, see Table 4.

**Table 4** vertex_filter parameter description
Parameter	Mandatory	Type	Description
leftvalue	No	String	Left value of the string type. For details, see leftvalue element formats.
predicate	Yes	String	Filtering type. The options are as follows: Logical operations: & and \| Note: leftvalue and rightvalue must be nested using property_filter. Only logical operations support nesting. Comparison operations: =, !=, >, >=, <, and <= Set operations: IN and NOTIN There is a difference in semantics between checking if leftvalue (label, ID, property value) is in rightvalue (which must be an array type) and whether there is an intersection between the left and right values of the memory edition. Set operations such as CONTAIN, NOTCONTAIN, and SUBSET are not supported. Matching: rightvalue is a PREFIX (prefix), NOTPREFIX (non-prefix), SUFFIX (suffix), NOTSUFFIX (non-suffix), SUBSTRING (substring), NOTSUBSTRING (non-substring), CISUBSTRING (case-insensitive substring), FUZZY (fuzzy match), or REGEX (regular match) of leftvalue. HAS/HASNOT: whether this property exists. Only property filtering is supported. That is, the left value can only be property_name.
rightvalue	Yes	String	Right value. For details about the format, see rightvalue element formats.

**Table 5** leftvalue elements
Parameter	Mandatory	Type	Description
label_name	No	String	Filter label. The value is labelName, which is optional.
property_name	No	String	Filter property. The value is the property name.
ID	No	String	Filter ID. This parameter is optional.
property_filter	No	String	Only when predicate is set to & or \|, property_filter can be nested in leftvalue and rightvalue.
degree	No	String	Direction of vertex degree filtering statistics. This parameter is optional. The value can be both, in, or out.

**Table 6** rightvalue elements
Parameter	Mandatory	Type	Description
value	Yes	String	1. Filter label. The value is the label name. 2. Filter property. The value is the property value. When predicate is HAS or HASNOT, the value is only a placeholder and has no meaning. 3. Filter ID. The value is the ID value. NOTE: If predicate is set to IN or NOTIN, the value of this parameter is of the List[string] type.
property_filter	No	String	If predicate is set to & or \|, property_filter can be nested in leftvalue and rightvalue.

Response Parameters

Parameter	Type	Description
errorMessage	String	System prompt. If execution succeeds, this parameter may be left blank. If the execution fails, this parameter is used to display the error message.
errorCode	String	System prompt. If execution succeeds, this parameter may be left blank. If the execution fails, this parameter is used to display the error code.
jobId	String	ID of the algorithm execution job. This parameter is left blank when the request fails. NOTE: You can use the returned job ID to view the task execution status and obtain the algorithm return result. For details, see Querying Job Status on the Service Plane (1.0.0).
jobType	Integer	Job type. This parameter is left blank when the request fails.

Example Request

POST http://{SERVER_URL}/ges/v1.0/{project_id}/hyg/{graph_name}/algorithm
{
    "algorithmName": "topicrank",
    "vertex_filter": {
        "property_filter": {
            "leftvalue": {
                "label_name": "labelName"
            },
            "predicate": "=",
            "rightvalue": {
                "value": "user"
            }
        }
    },
    "parameters": {
        "sources": "lili,andy",
        "alpha": 0.85,
        "convergence": 0.00001,
        "max_iterations": 1000,
        "filtered": "true"
    }
}

SERVER_URL: Address for accessing a graph. For details about its value, see Using Service Plane APIs.

Example request with vertex_filter

POST http://{SERVER_URL}/ges/v1.0/{project_id}/hyg/{graph_name}/algorithm
{
  "algorithmName": "topicrank",
  "parameters": {
    "sources": "lili,andy",
    "alpha": 0.85,
    "convergence": 0.00001,
    "max_iterations": 1000,
    "filtered": "true",
    "vertex_filter": {
      "property_filter": {
        "leftvalue": {
          "label_name": "labelName"
        },
        "predicate": "=",
        "rightvalue": {
          "value": "user"
        }
      }
    }
  }
}

Example Response

Status code: 200

Example response for a successful request

Http Status Code: 200
{  
"jobId": "4448c9fb-0b16-4a78-8d89-2a137c53454a001679122",
"jobType": 1
}

Status code: 400

Example response for a failed request

Http Status Code: 400
{
"errorMessage":"graph [demo] is not found",
"errorCode":"GES.8402"
}

Status Codes

Return Value	Description
400 Bad Request	Request error.
401 Unauthorized	Authorization failed.
403 Forbidden	No operation permissions.
404 Not Found	No resources found.
500 Internal Server Error	Internal server error.
503 Service Unavailable	Service unavailable.

Error Codes

See Error Codes for Service Plane APIs.

**Table 7** parameters parameter description
Parameter	Mandatory	Type	Description
source	Yes	String	Vertex ID
alpha	No	Double	Weight coefficient (also called damping coefficient). The value range is (0, 1). The default value is 0.85.
convergence	No	Double	Convergence. The value range is (0, 1). The default value is 0.00001.
max_iterations	No	Integer	Maximum iterations. An integer ranging from 1 to 2147483647. For frontend calls, the range is [1, 2000]. The default value is 1000.
num_thread	No	Integer	Number of concurrent threads. The value ranges from 1 to 40. If the value is less than 1, it is automatically set to 1. If the value is greater than 40, it is automatically set to 40. The default value is 4.
directed	No	Boolean	Whether to consider the edge direction. The value can be true or false. The default value is true.

For details about algorithm iterations and convergence, see Iterations and Convergence of PageRank.

**Table 8** response_data parameter description
Parameter	Type	Description
source	String	-
personalrank	List	PersonalRank value of each vertex. The format is as follows: [{vertexId:rankValue},...], where vertexId is of the string type. rankValue is of the double type.