Statistics REST APIs (Preview Feature)

The endpoints on this page calculate cardinality and histogram statistics of vertex and edge types and attributes. The statistics are required for effective optimization.

Query Optimizer is currently a Preview Feature. Preview Features give users an early look at future production-level features.

Preview Features should not be used for production deployments.

Cardinality

The following endpoints compute, fetch and delete vertex and edge counts (cardinality) of a graph.

Compute cardinality statistics

POST :14240/gsqlserver/gsql/stats/card

This endpoint computes the cardinality statistics for the vertex and edge types specified in the request. The cardinality statistics describe the number of vertices of a specified type, and the number of edges of a specified type between a specified pair of vertex types.

Parameters

Parameter Description Type

graph

Name of the graph. Required.

STRING

vertex

Vertex type to compute statistics for. You must provide either the vertex or edge parameter.

STRING

edge

Edge type to compute statistics for. You must provide either the vertex or edge parameter, but not both. If you provided it an edge type, you also need to provide the from and to parameters.

STRING

from

The source vertex type of an edge. Required if edge is provided.

STRING

to

The target vertex type of an edge. Required if edge is provided.

STRING

Examples

The following request computes cardinality for vertex type Person in the graph ldbc_snb:

curl -s --user tigergraph:tigergraph -X POST "http://localhost:14240/gsqlserver/gsql/stats/card?graph=ldbc_snb&vertex=Person"

The following request computes cardinality for edge type LIKES from Person to Post in the graph ldbc_snb:

curl -s --user tigergraph:tigergraph -X POST "http://localhost:14240/gsqlserver/gsql/stats/card?graph=ldbc_snb&edge=LIKES&from=Person&to=Post"

Retrieve cardinality statistics

GET :14240/gsqlserver/gsql/stats/card

This endpoint retrieves the cardinality statistics of a graph.

Parameters

Parameter Description Data type

graph

Name of the graph. Required.

STRING

Examples

The following request retrieves the cardinality data for graph ldbc_snb:

curl -s --user tigergraph:tigergraph -X GET "http://localhost:14240/gsqlserver/gsql/stats/card?graph=ldbc_snb"

Delete cardinality statistics

DELETE :14240/gsqlserver/gsql/stats/card

This endpoint deletes the cardinality statistics of a graph.

Parameters

Parameter Description Data type

graph

Name of the graph. Required.

STRING

Examples

The following request deletes the cardinality data for graph ldbc_snb:

curl -s --user tigergraph:tigergraph -X DELETE "http://localhost:14240/gsqlserver/gsql/stats/card?graph=ldbc_snb"

Histogram

Histograms store information about the distribution of attribute values.

Compute histogram statistics

POST :14240/gsqlserver/gsql/stats/histogram

This endpoint computes histograms for a specified attribute of a vertex type.

Parameters

No URL parameters. Provide parameters in the request body.

Request body

The request body expects a JSON object with the following schema:

  • Vertex attribute

  • Edge attribute

{
    "graph": <graph_name>,
    "vertex": <vertex_type_name>
    "attribute": <attribute_name>
    "bucket" <bucket_number>
}
{
    "graph": <graph_name>,
    "edge": <edge_type_name>,
    "attribute": <attribute_name>,
    "bucket" <bucket_number>,
    "from`: <source_vertex_type>,
    "to": <target_vertex_type>
}
Parameter Description Data type

graph

Name of the graph.

STRING

vertex

Name of the vertex type.

STRING

edge

Name of the refined edge type.

STRING

attribute

Name of the attribute.

STRING

bucket

The number of intervals (buckets) to divide the range of attribute values by.

It is recommended that each bucket have at least 100 values. Therefore, a good rule of thumb is to divide the number of vertices by 100 to decide the number of buckets. For example, if the vertex type has 100,000 vertices, set this parameter to no higher than 1000. A standard value for this parameter is 256.

INT

from

Source vertex type of a refined edge type.

STRING

to

Target edge type of a refined edge type.

STRING

Examples

The following request computes the histogram data for attribute firstName of vertex type Person on graph ldbc_snb:

$ curl --user tigergraph:tigergraph -X POST \
"http://localhost:14240/gsqlserver/gsql/stats/histogram" \
-d '{"graph":"ldbc_snb", "vertex":"Person", "attribute":"firstName", "buckets":10}'

To compute the histogram data for attribute creationDate from vertex type Person to vertex type Comment, make the following request:

$ curl --user tigergraph:tigergraph -X POST \
"http://localhost:14240/gsqlserver/gsql/stats/histogram" \
-d '{"graph":"ldbc_snb", "edge":"LIKES", "from":"Person", "to":"Comment", "attribute":"creationDate", "buckets":10}'

Retrieve histogram statistics

GET :14240/gsqlserver/gsql/stats/histogram

This endpoint retrieves histogram data for a specified attribute of a vertex type.

Parameters

Parameter Description Data type

graph

Name of the graph.

STRING

vertex

Name of the vertex type.

STRING

edge

Name of the refined edge type.

STRING

from

Source vertex type of a refined edge type.

STRING

to

Target edge type of a refined edge type.

STRING

attribute

Name of the attribute.

STRING

Examples

The following request retrieves the histogram statistics for the first_name attribute of the vertex type Person:

$ curl -s --user tigergraph:tigergraph -X GET "http://localhost:14240/gsqlserver/gsql/stats/histogram?graph=ldbc_snb&vertex=Person&attribute=firstName"

The following request retrieves the histogram statistics for the creationDate attribute of the refined edge type LIKES between Person and Comment:

$ curl --user tigergraph:tigergraph -X GET "http://localhost:14240/gsqlserver/gsql/stats/histogram?graph=ldbc_snb&edge=LIKES&attribute=creationDate&from=Person&to=Comment"

Delete histogram statistics

DELETE :14240/gsqlserver/gsql/stats/histogram

This endpoint deletes histogram data for a graph. This includes histogram data on all vertex attributes in that graph.

Parameters

Parameter Description Data type

graph

Name of the graph.

STRING

vertex

Name of the vertex type.

STRING

edge

Name of the refined edge type.

STRING

from

Source vertex type of a refined edge type.

STRING

to

Target edge type of a refined edge type.

STRING

attribute

Name of the attribute.

STRING

Examples

The following request deletes the histogram statistics for the graph ldbc_snb:

curl -s --user tigergraph:tigergraph -X DELETE "http://localhost:14240/gsqlserver/gsql/stats/histogram?graph=ldbc_snb

The following request deletes the histogram statistics for the creationDate attribute of the refined edge type LIKES between Person and Comment:

$ curl --user tigergraph:tigergraph -X DELETE "http://localhost:14240/gsqlserver/gsql/stats/histogram?graph=ldbc_snb&edge=LIKES&attribute=creationDate&from=Person&to=Comment"