Updated on 2025-08-22 GMT+08:00

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 are true and 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 descriptions

Parameter

Mandatory

Type

Description

leftvalue

No

String

Left value of the string type. For details, see Table 5.

predicate

Yes

String

Filtering type. The options are:

  • 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
    1. 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.
    2. 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 of a search criterion. For details about the format, see Table 6.

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 the 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 the 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).

topicrank

List

TopicRank value of each vertex. The format is:

[{vertexId:rankValue},...]

where,

vertexId is of the string type.

rankValue is of the double type.

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"
}

Status code: 400

Example response for a failed request

Http Status Code: 400
{
    "errorMessage": "Parameter error!",
    "errorCode": "GES.8005"
}

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.