---
title: "Statistics REST APIs (Preview Feature)"
component: "gsql-ref"
version: "3.11"
module: "querying"
html_url: "/gsql-ref/3.11/querying/query-optimizer/stats-api"
canonical_url: "https://www.tigergraph.com/docs/gsql-ref/3.11/querying/query-optimizer/stats-api"
markdown_url: "https://www.tigergraph.com/docs/gsql-ref/3.11/querying/query-optimizer/stats-api.md"
---

[View as HTML](https://www.tigergraph.com/docs/gsql-ref/3.11/querying/query-optimizer/stats-api)

# 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.

> [!NOTE]
> 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`:

```console
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`:

```console
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`:

```console
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`:

```console
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](https://en.wikipedia.org/wiki/Data%5Fbinning)) 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`:

```console
$ 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:

```console
$ 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`:

```console
$ 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`:

```console
$ 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`:

```console
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`:

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