---
title: "GSQL Endpoints"
description: "A set of GSQL REST API endpoints about vertex in TigerGraph server."
component: "tigergraph-server"
version: "4.3"
module: "API"
html_url: "/tigergraph-server/4.3/API/gsql-endpoints"
canonical_url: "https://www.tigergraph.com/docs/tigergraph-server/4.3/API/gsql-endpoints"
markdown_url: "https://www.tigergraph.com/docs/tigergraph-server/4.3/API/gsql-endpoints.md"
---

[View as HTML](https://www.tigergraph.com/docs/tigergraph-server/4.3/API/gsql-endpoints)

# GSQL Endpoints

Table of Contents

* [Schema](https://www.tigergraph.com/docs/tigergraph-server/4.3/API/gsql-endpoints.md#_schema)
* [Loading Jobs](https://www.tigergraph.com/docs/tigergraph-server/4.3/API/gsql-endpoints.md#_loading_jobs)
* [Data source](https://www.tigergraph.com/docs/tigergraph-server/4.3/API/gsql-endpoints.md#_data_source)
* [Query](https://www.tigergraph.com/docs/tigergraph-server/4.3/API/gsql-endpoints.md#_query)
* [Comparing the RESTPP and GSQL query endpoints](https://www.tigergraph.com/docs/tigergraph-server/4.3/API/gsql-endpoints.md#_comparing_the_restpp_and_gsql_query_endpoints)
* [Template query](https://www.tigergraph.com/docs/tigergraph-server/4.3/API/gsql-endpoints.md#_template_query)
* [Database Utilities](https://www.tigergraph.com/docs/tigergraph-server/4.3/API/gsql-endpoints.md#_database_utilities)
* [Security](https://www.tigergraph.com/docs/tigergraph-server/4.3/API/gsql-endpoints.md#_security)
* [SCIM APIs for users/groups](https://www.tigergraph.com/docs/tigergraph-server/4.3/API/gsql-endpoints.md#_scim_apis_for_usersgroups)
* [Statistics](https://www.tigergraph.com/docs/tigergraph-server/4.3/API/gsql-endpoints.md#_statistics)
* [User Defined Objects](https://www.tigergraph.com/docs/tigergraph-server/4.3/API/gsql-endpoints.md#_user_defined_objects)

This page describes the REST API endpoints accessible on a TigerGraph server. Assume all the sample requests and sample response are based on this sample schema (graph name is "financialGraph"):

> [!NOTE]
> In 4.0, the paths for most endpoints were revised to follow a more standard convention. Some functions were moved from the RESTPP server to the GSQL server for consistency. You can refer to the [REST endpoints for TigerGraph 3.x](https://www.tigergraph.com/docs/tigergraph-server/4.3/API/built-in-endpoints.md) for comparison.

> [!NOTE]
> As of version 4.1.2, JWT tokens can be used for authentication with GSQL server REST endpoints.

![financialGraph schema](https://www.tigergraph.com/docs/tigergraph-server/4.3/API/_images/financialGraph_schema.png) 

Figure 1\. Sample schema

## Schema

### show vertices

`GET /gsql/v1/schema/vertices`

Show all the local vertices on a graph or show all the global vertices

#### Parameters:

| Name | Required | Description |
| --- | --- | --- |
| `graph` | no | Specifies the graph for which vertices should be displayed. If not provided, it indicates that all global vertices should be shown. |

#### Example

Sample Request

```bash
curl -X GET -H 'Content-Type: application/json' -u user1:pwd123 "http://localhost:14240/gsql/v1/schema/vertices?graph=financialGraph"
```

Sample Response

```console
{"error":false,"message":"","results":[{"Config":{"STATS":"OUTDEGREE_BY_EDGETYPE"},"Attributes":[{"IsUsingNewSyntax":true,"AttributeType":{"Name":"STRING"},"AttributeName":"name","IsPrimaryKey":true},{"AttributeType":{"Name":"BOOL"},"AttributeName":"isBlocked"}],"PrimaryId":{"IsUsingNewSyntax":true,"AttributeType":{"Name":"STRING"},"AttributeName":"name","IsPrimaryKey":true},"Name":"Account"},{"Config":{"STATS":"OUTDEGREE_BY_EDGETYPE"},"Attributes":[{"IsUsingNewSyntax":true,"AttributeType":{"Name":"STRING"},"AttributeName":"name","IsPrimaryKey":true}],"PrimaryId":{"IsUsingNewSyntax":true,"AttributeType":{"Name":"STRING"},"AttributeName":"name","IsPrimaryKey":true},"Name":"City"},{"Config":{"STATS":"OUTDEGREE_BY_EDGETYPE"},"Attributes":[{"IsUsingNewSyntax":true,"AttributeType":{"Name":"STRING"},"AttributeName":"name","IsPrimaryKey":true},{"AttributeType":{"Name":"BOOL"},"AttributeName":"isBlocked"}],"PrimaryId":{"IsUsingNewSyntax":true,"AttributeType":{"Name":"STRING"},"AttributeName":"name","IsPrimaryKey":true},"Name":"Phone"}]}
```

---

### show a vertex

`GET /gsql/v1/schema/vertices/{vertexName}`

Show a local/global vertex.

#### Parameters:

| Name | Required | Description |
| --- | --- | --- |
| `graph` | no | Specifies the graph for which the vertex should be displayed. If not provided, it indicates that the global vertex should be shown. |

#### Example

Sample Request

```bash
curl -X GET -H 'Content-Type: application/json' -u user1:pwd123 "http://localhost:14240/gsql/v1/schema/vertices/Account?graph=financialGraph"
```

Sample Response

```console
{"error":false,"message":"","results":{"Config":{"STATS":"OUTDEGREE_BY_EDGETYPE"},"Attributes":[{"IsUsingNewSyntax":true,"AttributeType":{"Name":"STRING"},"AttributeName":"name","IsPrimaryKey":true},{"AttributeType":{"Name":"BOOL"},"AttributeName":"isBlocked"}],"PrimaryId":{"IsUsingNewSyntax":true,"AttributeType":{"Name":"STRING"},"AttributeName":"name","IsPrimaryKey":true},"Name":"Account"}}
```

---

### create vertex using gsql command

`POST /gsql/v1/schema/vertices`

Create global vertices using GSQL commands. The request body should contain one or more GSQL `CREATE VERTEX` statements. See the example below.

#### Parameters:

| Name | Required | Description |
| --- | --- | --- |
| `gsql` | no | Indicates whether to use GSQL command(s) to describe the creation. For this use case, it must be set to `true`. |

#### Example

Sample Request

```bash
curl -X POST -H 'Content-Type: application/json' -u user1:pwd123 "http://localhost:14240/gsql/v1/schema/vertices?gsql=true" -d '{"gsql":["CREATE VERTEX UserA (PRIMARY_ID user_id UINT, name STRING)", "CREATE VERTEX UserB (PRIMARY_ID user_id UINT, name STRING)"]}'
```

Sample Response

```console
{"error":false,"message":"Successfully create vertices: [UserA, UserB]"}
```

---

### add global vertices to a local graph

`POST /gsql/v1/schema/vertices`

Add existing global vertices to a local graph

#### Parameters:

| Name | Required | Description |
| --- | --- | --- |
| `graph` | no | Specifies the graph to which the global vertices should be added. Here must provide. |

#### Example

Sample Request

```bash
curl -X POST -H 'Content-Type: application/json' -u user1:pwd123 "http://localhost:14240/gsql/v1/schema/vertices?graph=financialGraph" -d '{"addVertices":["UserA","UserB"]}'
```

Sample Response

```console
{"error":false,"message":"Successfully add vertices: [UserA, UserB] on graph financialGraph"}
```

---

### create vertices (create vertices in global level)

`POST /gsql/v1/schema/vertices`

This api is used to create global vertices using json

#### Parameters:

None

#### Example

Sample Request

```bash
curl -X POST -H 'Content-Type: application/json' -u user1:pwd123 "http://localhost:14240/gsql/v1/schema/vertices" -d '{
    "createVertices": [
        {
            "Config": {
                "STATS": "OUTDEGREE_BY_EDGETYPE"
            },
            "Attributes": [
                {
                    "AttributeType": {
                        "Name": "STRING"
                    },
                    "AttributeName": "name"
                }
            ],
            "PrimaryId": {
                "AttributeType": {
                    "Name": "UINT"
                },
                "AttributeName": "user_id"
            },
            "Name": "User5"
        },
        {
            "Config": {
                "STATS": "OUTDEGREE_BY_EDGETYPE"
            },
            "Attributes": [
                {
                    "AttributeType": {
                        "Name": "STRING"
                    },
                    "AttributeName": "name"
                }
            ],
            "PrimaryId": {
                "AttributeType": {
                    "Name": "UINT"
                },
                "AttributeName": "user_id"
            },
            "Name": "User4"
        }
    ]
}'
```

Sample Response

```console
{"error":false,"message":"Successfully create vertices: [User5, User4]"}
```

---

### drop vertices

`DELETE /gsql/v1/schema/vertices`

Drop local vertices on specific graph or drop global vertices.

#### Parameters:

| Name | Required | Description |
| --- | --- | --- |
| `vertex` | yes | Specifies the vertex types to be deleted. If there are multiple vertex types, separate them with commas. Use "all" to delete all vertices. |
| `graph` | no | Specifies the graph from which vertices should be deleted. If not provided, it indicates that global vertices should be dropped. |

#### Example

Sample Request

```bash
curl -X DELETE -H "content-type: text/plain" -u user1:pwd123 "http://localhost:14240/gsql/v1/schema/vertices?vertex=user5,user4"
```

Sample Response

```console
{"error":false,"message":"Vertices [user5, user4] deleted successfully."}
```

---

### drop a vertex

`DELETE /gsql/v1/schema/vertices/{vertexName}`

Drop a local/global vertex.

#### Parameters:

| Name | Required | Description |
| --- | --- | --- |
| `graph` | no | Specifies the graph from which the vertex should be deleted. If not provided, it indicates that a global vertex should be dropped. |

#### Example

Sample Request

```bash
curl -X DELETE -H "content-type: text/plain" -u user1:pwd123 "http://localhost:14240/gsql/v1/schema/vertices/userB?graph=financialGraph"
```

Sample Response

```console
{"error":false,"message":"Vertices [userB] deleted successfully."}
```

---

### update a vertex attribute

`PUT /gsql/v1/schema/vertices/{vertexName}`

Update a vertex attributes.

#### Parameters:

| Name | Required | Description |
| --- | --- | --- |
| `graph` | no | Specifies the graph in which the vertex attributes should be updated. If not provided, it indicates that the attributes of a global vertex should be updated. |

#### Example

Sample Request

```bash
curl -X PUT -H "content-type: application/json" -u user1:pwd123 "http://localhost:14240/gsql/v1/schema/vertices/Account?graph=financialGraph" -d '{"dropAttributes":["isBlocked"],"addAttributes":[{"AttributeType":{"Name":"STRING"},"AttributeName":"attr1"}]}'
```

Sample Response

```console
{"error":false,"message":"Successfully update vertex: Account"}
```

---

### show all indexes

`GET /gsql/v1/schema/indexes`

Display all indexes within a specific graph or across all global vertices.

#### Parameters:

| Name | Required | Description |
| --- | --- | --- |
| `graph` | no | Specifies the graph for which to display indexes. If not provided, all indexes on global vertices will be shown. |

#### Example

Sample Request

```bash
curl -X GET -H "content-type: text/plain" -u user1:pwd123 "http://localhost:14240/gsql/v1/schema/indexes?graph=financialGraph"
```

Sample Response

```console
{"error":false,"message":"","results":[{"Account":[{"index":"index_type_name","attribute":"name"}]}]}
```

---

### show an index

`GET /gsql/v1/schema/indexes/{indexName}`

This endpoint endpoint is used to retrieve information about a specific index.

#### Parameters:

| Name | Required | Description |
| --- | --- | --- |
| `graph` | no | Specifies the graph in which the index is located. |

#### Example

Sample Request

```bash
curl -X GET -H "content-type: text/plain" -u user1:pwd123 "http://localhost:14240/gsql/v1/schema/indexes/index_type_name?graph=financialGraph"
```

Sample Response

```console
{"error":false,"message":"","results":{"index":"index_type_name","attribute":"name"}}
```

---

### create indexes

`POST /gsql/v1/schema/indexes`

Create indexes.

#### Parameters:

| Name | Required | Description |
| --- | --- | --- |
| `graph` | no | Specifies the graph where the indexes should be created. If not provided, the indexes will be created in the default graph. |

#### Example:

Sample Request

```bash
curl -X POST -H "content-type: text/plain" -u user1:pwd123 "http://localhost:14240/gsql/v1/schema/indexes?graph=financialGraph" -d '{"vertex":"Account","addIndexAttributes":[{"indexName":"nameIndex","attributeName":"name"}]}'
```

Sample Response

```console
{"error":false,"message":"Successfully add index nameIndex on attribute name\n"}
```

---

### drop an index

`DELETE /gsql/v1/schema/indexes/{indexName}`

Drop an index.

#### Parameters:

| Name | Required | Description |
| --- | --- | --- |
| `vertex` | yes | Specifies the vertex from which to drop the index |
| `graph` | no | Specifies the graph from which the index should be dropped. If not specified, the index will be dropped from the global vertex. |

#### Example:

Sample Request

```bash
curl -X DELETE -H "content-type: text/plain" -u user1:pwd123 "http://localhost:14240/gsql/v1/schema/indexes/nameIndex?vertex=Account"
```

Sample Response

```console
{"error":false,"message":"Successfully drop index"}
```

---

### drop indexes

`DELETE /gsql/v1/schema/indexes`

Drop indexes.

#### Parameters:

| Name | Required | Description |
| --- | --- | --- |
| `vertex` | yes | Specifies the vertex on which to drop the indexes. |
| `index` | yes | Specifies the indexes to drop (separated by commas) |
| `graph` | no | Specifies the graph from which the indexes should be dropped. |

#### Example:

Sample Request

```bash
curl -X DELETE -H "content-type: text/plain" -u user1:pwd123 "http://localhost:14240/gsql/v1/schema/indexes?graph=financialGraph&vertex=Account&index=nameIndex"
```

Sample Response

```console
{"error":false,"message":"Successfully drop index"}
```

---

### get all edges

`GET /gsql/v1/schema/edges`

Retrieve all local edges within a specific graph or retrieve all global edges.

#### Parameters:

| Name | Required | Description |
| --- | --- | --- |
| `graph` | no | Specifies the graph from which to retrieve the edges. If not provided, means to get all global edges. |

#### Example:

Sample Request

```bash
curl -X GET -H 'Content-Type: application/json' -u user1:pwd123 "http://localhost:14240/gsql/v1/schema/edges?graph=financialGraph"
```

Sample Response

```console
{"error":false,"message":"","results":[{"IsDirected":true,"ToVertexTypeName":"Account","Config":{"REVERSE_EDGE":"Transfer_Reverse"},"DiscriminatorCount":1,"Attributes":[{"AttributeType":{"Name":"DATETIME"},"IsDiscriminator":true,"AttributeName":"date"},{"AttributeType":{"Name":"UINT"},"AttributeName":"amount"}],"FromVertexTypeName":"Account","CompositeDiscriminator":["date"],"Name":"Transfer"},{"IsDirected":false,"ToVertexTypeName":"Phone","Config":{},"Attributes":[],"FromVertexTypeName":"Account","Name":"hasPhone"},{"IsDirected":true,"ToVertexTypeName":"City","Config":{},"Attributes":[],"FromVertexTypeName":"Account","Name":"isLocatedIn"}]}
```

---

### retrieve a specific edge type info

`GET /gsql/v1/schema/edges/{edgeName}`

Retrieve information about a specific edge type within a local graph, or retrieve information about a specific global edge type.

#### Parameters:

| Name | Required | Description |
| --- | --- | --- |
| `graph` | no | Specifies the graph in which the edge type is located. If not provided, it retrieves the global edge type information. |

#### Example:

Sample Request

```bash
curl -X GET -H 'Content-Type: application/json' -u user1:pwd123 "http://localhost:14240/gsql/v1/schema/edges/isLocatedIn?graph=financialGraph"
```

Sample Response

```console
{"error":false,"message":"","results":{"IsDirected":true,"ToVertexTypeName":"City","Config":{},"Attributes":[],"FromVertexTypeName":"Account","Name":"isLocatedIn"}}
```

---

### create edges using gsql command statement

`POST /gsql/v1/schema/edges`

Create global edges using GSQL commands. The request body should contain one or more GSQL `CREATE EDGE` statements. See the example below.

#### Parameters:

| Name | Required | Description |
| --- | --- | --- |
| `gsql` | no | Indicates whether to use GSQL command(s) to describe the creation. For this use case, it must be set to `true`. |

#### Example:

Sample Request

```bash
curl -X POST -H 'Content-Type: application/json' -u user1:pwd123 "http://localhost:14240/gsql/v1/schema/edges?gsql=true" -d '{"gsql":["CREATE UNDIRECTED EDGE edge1 (from Account, to City, attr1 float)", "CREATE UNDIRECTED EDGE edge2 (from Account, to Phone, attr2 float)"]}'
```

Sample Response

```console
{"error":false,"message":"Successfully create edges: [edge1, edge2]"}
```

---

### add global edges to graph using json format

`POST /gsql/v1/schema/edges`

Add global edges to graph using json format.

#### Parameters:

| Name | Required | Description |
| --- | --- | --- |
| `graph` | no | Specifies the graph to which the global edges will be added. Here must provide. |

#### Example:

Sample Request

```bash
curl -X POST -H "content-type: application/json" -H 'Content-Type: application/json' -u user1:pwd123 "http://localhost:14240/gsql/v1/schema/edges?graph=financialGraph" -d '{"addEdges":["has_account"]}'
```

Sample Response

```console
{"error":false,"message":"Successfully added edges [has_account] to graph financialGraph."}
```

---

### create global edges using json format

`POST /gsql/v1/schema/edges`

Create global edges using json format.

#### Parameters:

None

#### Example:

Sample Request

```bash
curl -X POST -H 'Content-Type: application/json' -u user1:pwd123 "http://localhost:14240/gsql/v1/schema/edges" -d ' {"createEdges":["IsDirected":true,"ToVertexTypeName":"City","Config":{},"Attributes":[],"FromVertexTypeName":"Account","Name":"isLocatedIn"},"IsDirected":true,"ToVertexTypeName":"Phone","Config":{},"Attributes":[],"FromVertexTypeName":"Account","Name":"hasPhone"}]}'
```

Sample Response

```console
{"error":false,"message":"Successfully create edges: [isLocatedIn, hasPhone]"}
```

---

### drop edges from graph

`DELETE /gsql/v1/schema/edges`

Drop edges from a graph or drop global edges.

#### Parameters:

| Name | Required | Description |
| --- | --- | --- |
| `edge` | yes | Specifies the edge types to be deleted. If there are multiple edge types, separate them with a comma. Use 'all' to drop all edges. |
| `graph` | no | Specifies the graph from which the edges will be deleted. If not provided, it means the operation will drop global edges. |

#### Example:

Sample Request

```bash
curl -X DELETE -H 'Content-Type: application/json' -u user1:pwd123 "http://localhost:14240/gsql/v1/schema/edges?edge=hasPhone&graph=financialGraph"
```

Sample Response

```console
{"error":false,"message":"Edges [hasPhone] deleted successfully."}
```

---

### drop an edge

`DELETE /gsql/v1/schema/edges/{edgeName}`

Drop a local/global edge.

#### Parameters:

| Name | Required | Description |
| --- | --- | --- |
| `graph` | no | Specifies the graph from which the edge will be deleted. If not provided, it means the operation will drop a global edge. |

#### Example:

Sample Request

```bash
curl -X DELETE -H "content-type: text/plain" -u user1:pwd123 "http://localhost:14240/gsql/v1/schema/edges/hasPhone?graph=financialGraph"
```

Sample Response

```console
{"error":false,"message":"Edges [hasPhone] deleted successfully."}
```

---

### update attribute in edge

`PUT /gsql/v1/schema/edges/{edgeName}`

Update attributes in edge.

#### Parameters:

| Name | Required | Description |
| --- | --- | --- |
| `graph` | no | Specifies the graph in which the edge's attributes will be updated. If not provided, it means the operation will update attributes on the global level. |

#### Example:

Sample Request

```bash
curl -X PUT -H 'Content-Type: application/json' -u user1:pwd123 "http://localhost:14240/gsql/v1/schema/edges/Transfer?graph=financialGraph" -d '{"dropAttributes":["date"],"addAttributes":[{"AttributeType":{"Name":"STRING"},"AttributeName":"attr"}]}'
```

Sample Response

```console
{"error":false,"message":"Successfully update edge: Transfer"}
```

---

### show all graphs info that only contains the name of vertices and edges

`GET /gsql/v1/schema/graphs`

Show all graphs info only containing names of vertices and edges.

#### Parameters:

None

#### Example:

Sample Request

```bash
curl -X GET -H 'Content-Type: application/json' -u user1:pwd123 "http://localhost:14240/gsql/v1/schema/graphs"
```

Sample Response

```console
{"graphs":[{"graphName":"financialGraph","vertices":["Account","City","Phone"],"edges":["Transfer","Transfer_Reverse","hasPhone","isLocatedIn"]}],"error":false,"message":""}
```

---

### show one graph detailed info with given graph name

`GET /gsql/v1/schema/graphs/{graph}`

Show one graph detailed info with given graph name.

#### Parameters:

None

#### Example:

Sample Request

```bash
curl -X GET -H "content-type: application/json" -u user1:pwd123 "http://localhost:14240/gsql/v1/schema/graphs/financialGraph"
```

Sample Response

```console
{"error":false,"message":"","results":{"GraphName":"financialGraph","VertexTypes":[{"Config":{"STATS":"OUTDEGREE_BY_EDGETYPE"},"Attributes":[{"AttributeType":{"Name":"BOOL"},"AttributeName":"isBlocked"},{"AttributeType":{"Name":"STRING"},"AttributeName":"name"}],"PrimaryId":{"AttributeType":{"Name":"UINT"},"AttributeName":"id"},"Name":"Account"},{"Config":{"STATS":"OUTDEGREE_BY_EDGETYPE"},"Attributes":[{"AttributeType":{"Name":"STRING"},"AttributeName":"name"}],"PrimaryId":{"AttributeType":{"Name":"UINT"},"AttributeName":"id"},"Name":"City"},{"Config":{"STATS":"OUTDEGREE_BY_EDGETYPE"},"Attributes":[{"AttributeType":{"Name":"BOOL"},"AttributeName":"isBlocked"},{"AttributeType":{"Name":"STRING"},"AttributeName":"number"}],"PrimaryId":{"AttributeType":{"Name":"UINT"},"AttributeName":"id"},"Name":"Phone"}],"EdgeTypes":[{"IsDirected":true,"ToVertexTypeName":"City","Config":{},"Attributes":[],"FromVertexTypeName":"Account","Name":"isLocatedIn"},{"IsDirected":true,"ToVertexTypeName":"Phone","Config":{},"Attributes":[],"FromVertexTypeName":"Account","Name":"hasPhone"}, {"IsDirected":false,"ToVertexTypeName":"Account","Config":{"REVERSE_EDGE":"Transfer_Reverse"},"Attributes":[{"AttributeType":{"Name":"UINT"},"AttributeName":"amount"},{"AttributeType":{"Name":"DATETIME"},"AttributeName":"date"}],"FromVertexTypeName":"Account","Name":"Transfer"}]}}
```

---

### create one graph using gsql command

`POST /gsql/v1/schema/graphs`

Create one graph using gsql command.

#### Parameters:

| Name | Required | Description |
| --- | --- | --- |
| `gsql` | no | default: false. Indicates whether to use the GSQL command for creation. Here must be set to true. The request body should contain the GSQL command within the JSON object. |
| `graphName` | yes | Specifies the name of the graph to be created. |

#### Example:

Sample Request

```bash
curl -X POST -H "content-type: application/json" "http://localhost:14240/gsql/v1/schema/graphs?gsql=true" -d '{"gsql": "create graph g(*)"}'
```

Sample Response

```console
{"error":false,"message":"Successfully created graph: [g]."}
```

---

### create one graph using JSON format

`POST /gsql/v1/schema/graphs`

Create one graph using JSON format.

#### Parameters:

| Name | Required | Description |
| --- | --- | --- |
| `gsql` | no | default: false. Indicates whether to use a GSQL command for graph creation. Here must set to false to use JSON format. |
| `graphName` | yes | Specifies the name of the graph to be created. |

#### Example:

Sample Request

```bash
curl -X POST -H "content-type: application/json" "http://localhost:14240/gsql/v1/schema/graphs?graphName=gtest&gsql=false
" -d '{"VertexTypes":["Account","Phone"], "EdgeTypes":["hasPhone"]}'
```

Sample Response

```console
{"error":false,"message":"Successfully created graph: [gtest]."}
```

---

### drop one graph

`DELETE /gsql/v1/schema/graphs/{graphName}`

Drop one graph.

#### Parameters:

| Name | Required | Description |
| --- | --- | --- |
| `cascade` | no | default: `false`. If set to `true`, it will automatically drop the queries and loading jobs associated with this graph. If set to `false`, the operation will fail if there are any existing queries or loading jobs related to the graph. |

#### Example:

Sample Request

```bash
curl -X DELETE -H "content-type: text/plain" "http://localhost:14240/gsql/v1/schema/graphs/financialGraph?cascade=true"
```

Sample Response

```console
{"error":false,"message":"Successfully dropped graph: financialGraph."}
```

---

### drop graphs with given names

`DELETE /gsql/v1/schema/graphs`

Drop graphs with given names.

#### Parameters:

| Name | Required | Description |
| --- | --- | --- |
| `graphNames` | yes | Specifies the names of the graphs to be dropped, separated by commas. Use 'all' to drop all graphs. |

#### Example:

Sample Request

```bash
curl -X DELETE -H "content-type: text/plain" "http://localhost:14240/gsql/v1/schema/graphs?graphNames=financialGraph,recommend"
```

Sample Response

```console
{"error":false,"message":"Successfully dropped graphs: [financialGraph, recommend]."}
```

---

### drop local/global schema change jobs

`DELETE /gsql/v1/schema/jobs`

Drop local/global schema change jobs.

#### Parameters:

| Name | Required | Description |
| --- | --- | --- |
| `jobName` | yes | Specifies the schema jobs to drop, separated by commas. |
| `graph` | no | Specifies the graph whose jobs are to be dropped. If not provided, means drop the global schema change jobs. |

#### Example:

Sample Request

```bash
curl -X DELETE -H "content-type: text/plain" "http://localhost:14240/gsql/v1/schema/jobs?jobName=test1,test2&graph=financialGraph"
```

Sample Response

```console
{"error":false,"message":"Successfully dropped schema change jobs: [test1, test2]."}
```

---

### create local/global schema change job using gsql command

`POST /gsql/v1/schema/jobs/{jobName}`

Create local/global schema change job using gsql command.

#### Parameters:

| Name | Required | Description |
| --- | --- | --- |
| `gsql` | no | Indicates whether to use the GSQL command for creation. Here must be set to true. The request body should contain the GSQL command within the JSON object. |
| `graph` | no | Which graph to create schema change. Global schema change doesn't need provide. |
| `type` | no | When creating a global schema change job, provide `global`. This is not required for local schema change jobs. |

#### Example:

Sample Request

```bash
curl -X POST -H "content-type: text/plain" "http://localhost:14240/gsql/v1/schema/jobs/test3?gsql=true&type=global" -d ' {"gsql" : "create global schema_change job test3 {add vertex website to graph financialGraph;}"}'
```

Sample Response

```console
{"error":false,"message":"Successfully created global schema change job: [test3]."}
```

---

### create global schema change job using json

`POST /gsql/v1/schema/jobs/{jobName}`

Create global schema change job using json.

#### Parameters:

None

#### Example:

Sample Request

```bash
curl -X POST -H "content-type: application/json" "http://localhost:14240/gsql/v1/schema/jobs/test4" -d '{"graphs": [{"graphName":"financialGraph","addVertexTypes":["user","website"],"dropVertexTypes":[], "dropEdgeTypes":[],"addEdgeTypes":[]}]}'
```

Sample Response

```console
{"error":false,"message":"Successfully created global schema change job: [test4]."}
```

---

### create local schema change job using json

`POST /gsql/v1/schema/jobs/{jobName}`

Create local schema change job using json.

#### Parameters:

| Name | Required | Description |
| --- | --- | --- |
| `graph` | no | The graph whose schema change job is to be created. Here should provide. |

#### Example:

Assuming we already have the following vertices and edges in the local graph financialGraph:

```none
VERTEX LocalAccount (
    name STRING PRIMARY KEY,
    isBlocked BOOL
)

VERTEX LocalCity (
    name STRING PRIMARY KEY
)

VERTEX LocalPhone (
    name STRING PRIMARY KEY,
    isBlocked BOOL
)

DIRECTED EDGE LocalTransfer (
    FROM Account,
    TO Account,
    DISCRIMINATOR(date DATETIME),
    amount UINT
) WITH REVERSE_EDGE="LocalTransfer_Reverse"

UNDIRECTED EDGE LocalhasPhone (
    FROM Account,
    TO Phone
)

DIRECTED EDGE LocalisLocatedIn (
    FROM Account,
    TO City
)
```

Sample Request

```bash
curl -X POST -H "content-type: application/json" -u user1:pwd123 "http://localhost:14240/gsql/v1/schema/jobs/test5?graph=financialGraph" -d '
{
    "dropVertexTypes": [
        "LocalPhone"
    ],
    "alterVertexTypes": [
        {
            "name": "LocalAccount",
            "addAttributes": [
                {
                    "DefaultValue": "defaultValue1",
                    "AttributeType": {
                        "Name": "STRING"
                    },
                    "AttributeName": "attr2"
                }
            ],
            "addIndexAttributes": [
                {
                    "indexName": "ppIndex",
                    "attributeName": "name"
                }
            ]
        }
    ],
    "addVertexTypes": [
        {
            "Config": {
                "STATS": "OUTDEGREE_BY_EDGETYPE"
            },
            "Attributes": [
                {
                    "AttributeType": {
                        "Name": "STRING"
                    },
                    "AttributeName": "name"
                }
            ],
            "PrimaryId": {
                "AttributeType": {
                    "Name": "UINT"
                },
                "AttributeName": "user_id"
            },
            "Name": "User5"
        },
        {
            "Config": {
                "STATS": "OUTDEGREE_BY_EDGETYPE"
            },
            "Attributes": [
                {
                    "AttributeType": {
                        "Name": "STRING"
                    },
                    "AttributeName": "name"
                }
            ],
            "PrimaryId": {
                "AttributeType": {
                    "Name": "UINT"
                },
                "AttributeName": "user_id"
            },
            "Name": "User4"
        }
    ],
    "addEdgeTypes": [
        {
            "IsDirected": true,
            "ToVertexTypeName": "User4",
            "Config": {

            },
            "IsLocal": true,
            "Attributes": [
                {
                    "AttributeType": {
                        "Name": "DATETIME"
                    },
                    "AttributeName": "live_date"
                }
            ],
            "FromVertexTypeName": "User5",
            "Name": "edge1"
        }
    ],
    "dropEdgeTypes": [
        "LocalhasPhone"
    ],
    "alterEdgeTypes": [
        {
            "dropAttributes": [
                "amount"
            ],
            "addAttributes": [
                {
                    "DefaultValue": "defaultValue1",
                    "AttributeType": {
                        "Name": "STRING"
                    },
                    "AttributeName": "attr2"
                }
            ],
            "name": "LocalTransfer"
        }
    ]
}'
```

Sample Response

```console
{"error":false,"message":"Successfully created schema change job: [test5]."}
```

---

### get a specific local/global schema change job

`GET /gsql/v1/schema/jobs/{jobName}`

Retrieve a specific local/global schema change job.

#### Parameters:

| Name | Required | Description |
| --- | --- | --- |
| `graph` | no | the graph whose schema change job to show. don't provide this if get a global schema change job. |
| `json` | yes | Set to `true` to receive the response in JSON format; otherwise, the response will be in text format. |

#### Example:

Sample Request

```bash
curl -X GET -H "content-type: application/json" "http://localhost:14240/gsql/v1/schema/jobs/job12?json=true&graph=financialGraph"
```

Sample Response

```console
{"error":false,"message":"","results":{"job12":{"dropVertexTypes":[],"addTags":[],"name":"job12","alterVertexTypes":[],"addVertexTypes":[{"Config":{"STATS":"OUTDEGREE_BY_EDGETYPE"},"Attributes":[{"IsUsingNewSyntax":true,"AttributeType":{"Name":"STRING"},"AttributeName":"name","IsPrimaryKey":true},{"AttributeType":{"Name":"BOOL"},"AttributeName":"isBlocked"}],"PrimaryId":{"IsUsingNewSyntax":true,"AttributeType":{"Name":"STRING"},"AttributeName":"name","IsPrimaryKey":true},"Name":"LocalAccount"},{"Config":{"STATS":"OUTDEGREE_BY_EDGETYPE"},"Attributes":[{"IsUsingNewSyntax":true,"AttributeType":{"Name":"STRING"},"AttributeName":"name","IsPrimaryKey":true}],"PrimaryId":{"IsUsingNewSyntax":true,"AttributeType":{"Name":"STRING"},"AttributeName":"name","IsPrimaryKey":true},"Name":"LocalCity"},{"Config":{"STATS":"OUTDEGREE_BY_EDGETYPE"},"Attributes":[{"IsUsingNewSyntax":true,"AttributeType":{"Name":"STRING"},"AttributeName":"name","IsPrimaryKey":true},{"AttributeType":{"Name":"BOOL"},"AttributeName":"isBlocked"}],"PrimaryId":{"IsUsingNewSyntax":true,"AttributeType":{"Name":"STRING"},"AttributeName":"name","IsPrimaryKey":true},"Name":"LocalPhone"}],"addEdgeTypes":[{"IsDirected":true,"ToVertexTypeName":"Account","Config":{"REVERSE_EDGE":"LocalTransfer_Reverse"},"DiscriminatorCount":1,"Attributes":[{"AttributeType":{"Name":"DATETIME"},"IsDiscriminator":true,"AttributeName":"date"},{"AttributeType":{"Name":"UINT"},"AttributeName":"amount"}],"FromVertexTypeName":"Account","Name":"LocalTransfer"},{"IsDirected":false,"ToVertexTypeName":"Phone","Config":{},"Attributes":[],"FromVertexTypeName":"Account","Name":"LocalhasPhone"},{"IsDirected":true,"ToVertexTypeName":"City","Config":{},"Attributes":[],"FromVertexTypeName":"Account","Name":"LocalisLocatedIn"}],"dropEdgeTypes":[],"graph":"financialGraph","alterEdgeTypes":[],"dropTags":[]}}}
```

---

### run global schema change job directly

`POST /gsql/v1/schema/change`

Run global schema change job directly.

#### Parameters:

| Name | Required | Description |
| --- | --- | --- |
| `force` | no | If true, abort any loading jobs which have a schema conflict with this change. See [Run Schema Change options](https://www.tigergraph.com/docs/gsql-ref/4.3/ddl-and-loading/modifying-a-graph-schema.md#_run_schema_change_options). |

#### Example:

Sample Request

```bash
curl -X POST -H "content-type: application/json" -u user1:pwd123 "http://localhost:14240/gsql/v1/schema/change" -d '
 {"addVertexTypes":[{"Config":{"STATS":"OUTDEGREE_BY_EDGETYPE"},"Attributes":[{"AttributeType":{"Name":"STRING"},"AttributeName":"name"}],"PrimaryId":{"AttributeType":{"Name":"UINT"},"AttributeName":"user_id"},"Name":"User5"},
{"Config":{"STATS":"OUTDEGREE_BY_EDGETYPE"},"Attributes":[{"AttributeType":{"Name":"STRING"},"AttributeName":"name"}],"PrimaryId":{"AttributeType":{"Name":"UINT"},"AttributeName":"user_id"},"Name":"User4"}
]}'
```

Sample Response

```console
{"error":false,"message":"Global schema change runs successfully"}
```

---

### run the schema change job directly

`POST /gsql/v1/schema/change`

Run the schema change job directly.

#### Parameters:

| Name | Required | Description |
| --- | --- | --- |
| `graph` | no | which graph to run the local schema change job on, run local schema change need provide this. If not provided, means running global schema change job. |
| `force` | no | If true, abort any loading jobs which have a schema conflict with this change. See [Run Schema Change options](https://www.tigergraph.com/docs/gsql-ref/4.3/ddl-and-loading/modifying-a-graph-schema.md#_run_schema_change_options). |

#### Example:

Sample Request

```bash
curl -X POST -H "content-type: application/json" "http://localhost:14240/gsql/v1/schema/change?graph=financialGraph" -d '
{
    "dropVertexTypes": [],
    "alterVertexTypes": [
        {
            "name": "LocalAccount",
            "dropAttributes": [],
            "addAttributes": [
                {
                    "DefaultValue": "defaultValue1",
                    "AttributeType": {
                        "Name": "STRING"
                    },
                    "AttributeName": "attr2"
                }
            ],
            "dropIndexAttributes": [],
            "addIndexAttributes": [
                {
                    "indexName": "xIndex",
                    "attributeName": "name"
                },
                {
                    "indexName": "yIndex",
                    "attributeName": "isBlocked"
                }
            ]
        }
    ],
    "addVertexTypes": [
        {
            "Config": {
                "STATS": "OUTDEGREE_BY_EDGETYPE"
            },
            "Attributes": [
                {
                    "AttributeType": {
                        "Name": "STRING"
                    },
                    "AttributeName": "name"
                }
            ],
            "PrimaryId": {
                "AttributeType": {
                    "Name": "UINT"
                },
                "AttributeName": "user_id"
            },
            "Name": "User5"
        },
        {
            "Config": {
                "STATS": "OUTDEGREE_BY_EDGETYPE"
            },
            "Attributes": [
                {
                    "AttributeType": {
                        "Name": "STRING"
                    },
                    "AttributeName": "name"
                }
            ],
            "PrimaryId": {
                "AttributeType": {
                    "Name": "UINT"
                },
                "AttributeName": "user_id"
            },
            "Name": "User4"
        }
    ],
    "addEdgeTypes": [
        {
            "IsDirected": true,
            "ToVertexTypeName": "User4",
            "Config": {},
            "IsLocal": true,
            "Attributes": [
                {
                    "AttributeType": {
                        "Name": "DATETIME"
                    },
                    "AttributeName": "live_date"
                }
            ],
            "FromVertexTypeName": "User5",
            "Name": "edge1"
        }
    ],
    "dropEdgeTypes": [],
    "alterEdgeTypes": [
        {
            "dropAttributes": ["isBlocked"],
            "addAttributes": [
                {
                    "DefaultValue": "defaultValue1",
                    "AttributeType": {
                        "Name": "STRING"
                    },
                    "AttributeName": "attr2"
                }
            ],
            "name": "LocalPhone"
        }
    ]
}'
```

Sample Response

```console
{"error":false,"message":"Schema change job runs successfully"}
```

#### Example: Create a reverse edge type

You can automatically create a reverse edge type when adding a directed edge by specifying the `REVERSE_EDGE` option in the `Config` field.

Sample Request

```bash
curl -X POST -H "content-type: application/json" "http://localhost:14240/gsql/v1/schema/change?graph=exampleGraph" -d '
{
    "addEdgeTypes": [
        {
            "IsDirected": true,
            "FromVertexTypeName": "User5",
            "ToVertexTypeName": "User4",
            "Name": "edge1",
            "IsLocal": true,
            "Config": {
                "REVERSE_EDGE": "edge1_rev"
            },
            "Attributes": [
                {
                    "AttributeType": {
                        "Name": "DATETIME"
                    },
                    "AttributeName": "live_date"
                }
            ]
        }
    ]
}'
```

Sample Response

```console
{"error":false,"message":"Schema change job runs successfully"}
```

This creates both the forward edge `edge1` and the reverse edge `edge1_rev`.

---

### run an existing schema change job

`POST /gsql/v1/schema/jobs/{jobName}`

Run an existing schema change job.

#### Parameters:

| Name | Required | Description |
| --- | --- | --- |
| `graph` | no | which graph to run the schema change job on. If not provided, means run the global schema change job. |
| `force` | no | If true, abort any loading jobs which have a schema conflict with this change. See [Run Schema Change options](https://www.tigergraph.com/docs/gsql-ref/4.3/ddl-and-loading/modifying-a-graph-schema.md#_run_schema_change_options). |

#### Example:

Sample Request

```bash
curl -X POST -H "content-type: application/json" "http://localhost:14240/gsql/v1/schema/jobs/test5?graph=financialGraph"
```

Sample Response

```console
{"error":false,"message":"Schema change job run successfully!"}
```

---

### get latest schema version

`GET /gsql/v1/schema/version`

Retrieve the current committed schema version.

#### Permissions

Requires the `READ SCHEMA` privilege.

#### Parameters:

None

#### Example:

Sample Request

```bash
curl -u user1:pwd123 'http://<tigergraph-host>:14240/gsql/v1/schema/version'
```

Sample Response

```console
{
  "error": false,
  "message": "",
  "version": 1
}
```

> [!NOTE]
> * The `version` field is always returned as an **integer**.
> * If a schema change job is running but not yet committed, this endpoint still returns the old version.
> * Once the schema change is successfully committed, it returns the new version.

### get schema change jobs

`GET /gsql/v1/schema/jobs`

Get all local/global schema change jobs.

#### Parameters

| Name | Required | Description |
| --- | --- | --- |
| `graph` | no | The graph whose schema change job to show. If not provided, means to get all the global schema change job. |
| `json` | yes | Set to `true` means response in JSON format; otherwise, the response will be in text format. |

#### Example:

Sample Request

```bash
curl -X GET -H "content-type: application/json" -u user1:pwd123 "http://localhost:14240/gsql/v1/schema/jobs?graph=financialGraph"
```

Sample Response

```console
{"error":false,"message":"","results":[{"job12":"CREATE SCHEMA_CHANGE JOB job12 FOR GRAPH financialGraph {\n      ADD VERTEX LocalAccount(name STRING primary key, isBlocked BOOL) WITH STATS=\"OUTDEGREE_BY_EDGETYPE\";\n      ADD VERTEX LocalCity(name STRING primary key) WITH STATS=\"OUTDEGREE_BY_EDGETYPE\";\n      ADD VERTEX LocalPhone(name STRING primary key, isBlocked BOOL) WITH STATS=\"OUTDEGREE_BY_EDGETYPE\";\n      ADD DIRECTED EDGE LocalTransfer(FROM Account, TO Account, DISCRIMINATOR( date DATETIME), amount UINT) WITH REVERSE_EDGE=\"LocalTransfer_Reverse\";\n      ADD UNDIRECTED EDGE LocalhasPhone(FROM Account, TO Phone);\n      ADD DIRECTED EDGE LocalisLocatedIn(FROM Account, TO City);\n    }\n"},{"test5":"CREATE SCHEMA_CHANGE JOB test5 {\n      ADD VERTEX User5(PRIMARY_ID user_id UINT, name STRING) WITH STATS=\"OUTDEGREE_BY_EDGETYPE\";\n      ADD VERTEX User4(PRIMARY_ID user_id UINT, name STRING) WITH STATS=\"OUTDEGREE_BY_EDGETYPE\";\n      ADD DIRECTED EDGE edge1(FROM User5, TO User4, live_date DATETIME);\n      DROP VERTEX LocalPhone;\n      DROP EDGE LocalhasPhone;\n      ALTER VERTEX LocalAccount ADD ATTRIBUTE (attr2 STRING DEFAULT \"defaultValue1\");\n      ALTER VERTEX LocalAccount ADD INDEX ppIndex ON (name);\n      ALTER EDGE LocalTransfer ADD ATTRIBUTE (attr2 STRING DEFAULT \"defaultValue1\");\n      ALTER EDGE LocalTransfer DROP ATTRIBUTE (amount);\n    }\n"}]}
```

---

## Loading Jobs

### Get loading job names

`GET /gsql/v1/loading-jobs`

Get the names of all loading jobs in the given graph.

#### Parameters:

| Name | Required | Description |
| --- | --- | --- |
| `graph` | yes | name of the graph that these jobs belong to |

#### Example

Sample Request

```bash
curl -H 'Content-Type: application/json' -X GET
'http://localhost:14240/gsql/v1/loading-jobs?graph=financialGraph'
```

Sample Response

```console
{"error":false,"message":"","jobNames":["incidents_fraud_report_company_csv"]}
```

---

### Get loading job information

`GET /gsql/v1/loading-jobs/{jobName}`

Get information about a specific loading job.

#### Parameters:

| Name | Required | Description |
| --- | --- | --- |
| `graph` | yes | name of the graph that this job belongs to |
| `verbose` | no | If `true`: show more details.  If `false` (default): show fewer details. |

#### Example

Sample Request

```bash
curl -H 'Content-Type: applicaiton/json' -X GET
'http://localhost:14240/gsql/v1/loading-jobs/incidents_fraud_report_company_csv?graph=financialGraph&json=[true/false]'
```

Sample Response

json=false:

```console
{"error":false,"message":"","results":{"jobName":"incidents_fraud_report_company_csv","jobContent":"this is jobContent"}}
```

json=true:

```console
{"error":false,"message":"","results":{"Filters":[],"GraphName":"g","Headers":{"f1_header":["report_id","report_updated_at","report_status","report_type","report_source","report_data_source","fraud_type","tax_id"],"f1_header_company":["tax_id","report_updated_at","tax_status"]},"JobName":"incidents_fraud_report_company_csv","FileNames":{"f1":""},"LoadingStatements":[{"Type":"Vertex","UsingClauses":{"QUOTE":"double","EOL":"\\n","SEPARATOR":",","HEADER":"true","USER_DEFINED_HEADER":"f1_header"},"Mappings":[{"Type":"SrcColName","Value":"report_id"},{"Type":"SrcColName","Value":"report_updated_at"},{"Type":"SrcColName","Value":"report_status"},{"Type":"SrcColName","Value":"report_type"},{"Type":"SrcColName","Value":"report_source"},{"Type":"SrcColName","Value":"report_data_source"},{"Type":"SrcColName","Value":"fraud_type"}],"TargetName":"FraudReport","DataSource":{"Type":"FileVar","Value":"f1"}},{"Type":"Vertex","UsingClauses":{"QUOTE":"double","EOL":"\\n","SEPARATOR":",","HEADER":"true","USER_DEFINED_HEADER":"f1_header_company"},"Mappings":[{"Type":"SrcColName","Value":"tax_id"},{"Type":"SrcColName","Value":"report_updated_at"},{"Type":"SrcColName","Value":"tax_status"}],"TargetName":"Company","DataSource":{"Type":"FileVar","Value":"f1"}},{"Type":"Edge","UsingClauses":{"QUOTE":"double","EOL":"\\n","SEPARATOR":",","HEADER":"true","USER_DEFINED_HEADER":"f1_header"},"Mappings":[{"Type":"SrcColName","Value":"report_id"},{"Type":"SrcColName","Value":"tax_id"}],"TargetName":"HasIncident","FromVertexType":"FraudReport","ToVertexType":"Company","DataSource":{"Type":"FileVar","Value":"f1"}}]}}
```

---

### Create a loading job

`POST /gsql/v1/loading-jobs`

Create a new loading job, equivalent to GSQL[CREATE LOADING JOB](https://www.tigergraph.com/docs/gsql-ref/4.3/ddl-and-loading/creating-a-loading-job.md#_create_loading_job).

#### Parameters:

| Name | Required | Description |
| --- | --- | --- |
| `graph` | yes | name of the graph that this job will belong to |

#### Example

Sample Request

```bash
curl -H 'Content-Type: text/plain' -X POST 'http://localhost:14240/gsql/v1/loading-jobs?graph=financialGraph'
-d 'CREATE LOADING JOB load_kafka {
  DEFINE FILENAME f1 = "$ka:/tmp/kafka_topic.json";
  LOAD f1
    TO VERTEX company VALUES($0, $1, "2")
    USING SEPARATOR=",";
}'
```

Sample Response

```console
{"error":false,"message":"Successfully created loading job: load_kafka"}
```

---

### Update a loading job

`PUT /gsql/v1/loading-jobs`

Update an existing loading job.

#### Parameters:

| Name | Required | Description |
| --- | --- | --- |
| `graph` | yes | name of the graph that this job belongs to |

#### Example

Sample Request

```bash
curl -H 'Content-Type: text/plain' -X PUT 'http://localhost:14240/gsql/v1/loading-jobs?graph=financialGraph'
-d 'CREATE LOADING JOB load_kafka {
  DEFINE FILENAME f1 = "$ka:/tmp/kafka_topic.json";
  LOAD f1
    TO VERTEX company VALUES($0, $1, "3")
    USING SEPARATOR=",";
}'
```

Sample Response

```console
{"error":false,"message":"Successfully created loading job: load_kafka"}
```

---

### Drop a loading job

`DELETE /gsql/v1/loading-jobs/{jobName}`

Drop a loading job, equivalent to GSQL[DROP JOB](https://www.tigergraph.com/docs/gsql-ref/4.3/ddl-and-loading/creating-a-loading-job.md#_drop_job_statement).

#### Parameters:

| Name | Required | Description |
| --- | --- | --- |
| `graph` | yes | name of the graph that this job belongs to |

#### Example

Sample Request

```bash
curl -H 'Content-Type: application/json' -X DELETE
'http://localhost:14240/gsql/v1/loading-jobs/load_kafka?graph=financialGraph'
```

Sample Response

```console
{"error": false,"message":"Successfully drop loading job 'load_kafka'."}
```

---

### Run a loading job

`POST /gsql/v1/loading-jobs/run`

> [!NOTE]
> This endpoint runs GSQL loading jobs, including jobs that read Parquet data from cloud storage using a cloud file descriptor with `file.type` set to `parquet`. See [Cloud file descriptors](https://www.tigergraph.com/docs/tigergraph-server/4.3/data-loading/load-from-cloud.md#_cloud_file_descriptors) 

Run a loading job, equivalent to GSQL[RUN LOADING JOB](https://www.tigergraph.com/docs/gsql-ref/4.3/ddl-and-loading/running-a-loading-job.md#_run_loading_job).

#### Parameters:

| Name | Required | Description |
| --- | --- | --- |
| `graph` | yes | name of the graph that this job belongs to |

The request body is a JSON array of job objects. Each element runs one loading job; multiple elements run multiple jobs in a single call.

#### Job object

Each job object supports the following fields:

| Field | Type | Description |
| --- | --- | --- |
| `name` | string | Loading job name. Required. |
| `options` | object | Optional. CLI-style flags. See options table below. |
| `parameters` | object | Optional. GSQL USING key/value clauses: `EOF`, `CONCURRENCY`, `BATCH_SIZE`. |
| `dataSources` | array | One entry per data source referenced by the job. See dataSources table below. |

#### options

Use these flags to control loading behavior:

| Field | Type | Description |
| --- | --- | --- |
| `verbose` | bool | Verbose logging. |
| `dryrun` | bool | Validate without loading. |
| `maxNumError` | integer | Stop after this many bad records. |
| `maxPercentError` | integer | Stop when error rate exceeds this percent. |

#### dataSources

Each data source entry uses the following fields:

| Field | Type | Description |
| --- | --- | --- |
| `name` | string | For local files: `file`, `file:any`, `file:all`, `file:<machine>`, or `file:<m1>\|<m2>\|<m3>`. Otherwise, the name of a data source created via `CREATE DATA_SOURCE`. |
| `path` | string | Shorthand value — a file path, Kafka topic name, or SQL query string. Use either `path` or `config`, not both. |
| `config` | object | Full JSON config for the data source. Use when you need more than a single shorthand value (e.g., multiple URIs, reader overrides, `tasks.max`). Use either `config` or `path`, not both. |

#### Examples

Snowflake loading using a query string as path

```json
[
  {
    "name": "load_member_sf",
    "dataSources": [
      { "filename": "f", "name": "sf1", "path": "SELECT id, name FROM members LIMIT 1000" }
    ]
  }
]
```

Kafka loading using topic and partition config

```json
[
  {
    "name": "load_member_kafka_full",
    "dataSources": [
      {
        "filename": "f",
        "name": "kfka1",
        "config": {
          "topic": "members-topic",
          "partition.list": "0,1,2",
          "offset": "-2"
        }
      }
    ]
  }
]
```

Sample Request

```bash
curl -H 'Content-Type: application/json' -X POST \
  -d '[{"name":"load_member","options":{"verbose":true,"maxNumError":100},"parameters":{"BATCH_SIZE":10000},"dataSources":[{"filename":"f","name":"file:m1","path":"/data/members.csv"}]}]' \
  'http://localhost:14240/gsql/v1/loading-jobs/run?graph=financialGraph'
```

Sample Response

```console
{"error":false,"message":"","messages":"Successfully ran loading job(s): [load_member].","jobIds":["financialGraph.load_member.file.m1.1779266068037"]}
```

> [!NOTE]
> For the parameters:
> 
> * The top level `name` field is for the loading job name, while the `name` field in the `dataSources` array is for the data source file name.
> * The three keys inside the `configs` object are case-insensitive. However, other keys in the JSON payload are case-sensitive.

We have details of the [options](https://www.tigergraph.com/docs/gsql-ref/4.3/ddl-and-loading/running-a-loading-job.md#_options) and [parameters](https://www.tigergraph.com/docs/gsql-ref/4.3/ddl-and-loading/running-a-loading-job.md#_parameters) available for running a loading job in GSQL.

---

### List running loading jobs

`GET /gsql/v1/loading-jobs/listrunning`

This endpoint retrieves all currently running loading jobs that the user has permission to view. It also includes a `hasRunning` field in the response. If there are running jobs, even if the user does not have permission to view them, `hasRunning` will still be true.

#### Parameters:

| Name | Required | Description |
| --- | --- | --- |
| `graph` | yes | If provided, shows running loading jobs for the specified graph. If omitted, shows jobs for all graphs the user has access to. |

#### Permissions:

* Requires **READ Loading Job** privilege on the graph.
* If the user has **READ Loading Job** on a specific job only (not the whole graph), the API still returns information about that job.

#### Example

Sample Request

```bash
curl -u user1:pwd123 'http://<tigergraph-host>:14240/gsql/v1/loading-jobs/listrunning?graph=graphName'
```

Sample Response

```console
{
   "result":{
      "graph1.load_kafka.kafka.k1.1.1750837177278":"RUNNING",
      "graph2.load_kafka.kafka.k1.1.1750837174322":"RUNNING"
   },
   "hasRunning":true,
   "error":false,
   "message":""
}
```

---

### Get loading job run statuses (multiple jobs)

`GET /gsql/v1/loading-jobs/status`

Get the status of one or more loading jobs that have been started, equivalent to GSQL[SHOW LOADING STATUS](https://www.tigergraph.com/docs/gsql-ref/4.3/ddl-and-loading/managing-loading-job.md#_show_loading_status).

#### Parameters:

| Name | Required | Description |
| --- | --- | --- |
| `jobIds` | yes | ID of the loading job |

#### Example

Sample Request

```bash
curl -H 'Content-Type: application/json' -X GET
'http://localhost:14240/gsql/v1/loading-jobs/status/jobIds=financialGraph.load_ldbc_snb.jdbc.all.1111111111121'
```

Sample Response

```console
{"error":false,"message":"","results":[{"overall":{"averageSpeed":66666,"currentSpeed":55555,"duration":12345,"endTime":1111111123456,"id":"financialGraph.load_ldbc_snb.jdbc.all.1111111111121","progress":0,"size":1236,"startTime":1111111111111,"statistics":{"fileLevel":{"validLine":8},"objectLevel":{"vertex":[{"invalidAttribute":1,"noIdFound":1,"typeName":"Post","validObject":6}]}}},"workers":[{"tasks":[{"filename":"f1"}]}]}]}
```

---

### Get loading job run status (one job)

`GET /gsql/v1/loading-jobs/status/{jobId}`

Get the status of one loading job that has been started. The behavior of this endpoint is the same as that of `GET /gsql/v1/loading-jobs/status/` when only one `jobIds` parameter is used.

#### Parameters:

| Name | Required | Description |
| --- | --- | --- |
| `jobId` | yes | ID of the loading job |

#### Example

Sample Request

```bash
curl -H 'Content-Type: application/json' -X GET
'http://localhost:14240/gsql/v1/loading-jobs/status/financialGraph.load_ldbc_snb.jdbc.all.1111111111121'
```

Sample Response

```console
{"error":false,"message":"","results":[{"overall":{"averageSpeed":66666,"currentSpeed":55555,"duration":12345,"endTime":1111111123456,"id":"financialGraph.load_ldbc_snb.jdbc.all.1111111111121","progress":0,"size":1236,"startTime":1111111111111,"statistics":{"fileLevel":{"validLine":8},"objectLevel":{"vertex":[{"invalidAttribute":1,"noIdFound":1,"typeName":"Post","validObject":6}]}}},"workers":[{"tasks":[{"filename":"f1"}]}]}]}
```

---

### Abort loading job(s)

`GET /gsql/v1/loading-jobs/abort`

Abort one or more loading jobs, equivalent to GSQL[ABORT LOADING JOB](https://www.tigergraph.com/docs/gsql-ref/4.3/ddl-and-loading/managing-loading-job.md#_abort_loading_job).

#### Parameters:

| Name | Required | Description |
| --- | --- | --- |
| `graph` | yes | name of the graph that this job belongs to |
| `jobIds` | yes | ID of one of the loading jobs |

#### Example

Sample Request

```bash
curl -H 'Content-Type: application/json' -X GET
'http://localhost:14240/gsql/v1/loading-jobs/abort?graph=financialGraph&jobIds=jobId1'

curl -H 'Content-Type: application/json' -X GET
'http://localhost:14240/gsql/v1/loading-jobs/abort?graph=financialGraph&jobIds=jobId2&isPause=true'
```

Sample Response

```console
{"error": false,"message":"Successfully aborted loading job(s): [jobId1]."}

{"error": false,"message":"Successfully paused loading job(s): [jobId2]."}
```

---

### Abort one loading job

`GET /gsql/v1/loading-jobs/abort/{jobId}`

Abort one loading job, equivalent to GSQL[ABORT LOADING JOB](https://www.tigergraph.com/docs/gsql-ref/4.3/ddl-and-loading/managing-loading-job.md#_abort_loading_job). The behavior of this endpoint is the same as that of `GET /gsql/v1/loading-jobs/abort/` when only one `jobIds` parameter is used.

#### Parameters:

| Name | Required | Description |
| --- | --- | --- |
| `graph` | yes | name of the graph that this job belongs to |
| `jobId` | yes | ID of the loading job |

#### Example

Sample Request

```bash
curl -H 'Content-Type: application/json' -X GET 'http://localhost:14240/gsql/v1/loading-jobs/jobId1?graph=financialGraph'
```

Sample Response

```console
{"error": false,"message":"Successfully aborted loading job(s): [jobId1]."}
```

---

### Resume loading job

`GET /gsql/v1/loading-jobs/resume/{jobId}`

Resume a paused/aborted loading job, equivalent to GSQL[RESUME LOADING JOB](https://www.tigergraph.com/docs/gsql-ref/4.3/ddl-and-loading/managing-loading-job.md#_resume_loading_job).

#### Parameters:

| Name | Required | Description |
| --- | --- | --- |
| `jobId` | yes | ID of the loading job |

#### Example

Sample Request

```bash
curl -H 'Content-Type: application/json' -X GET 'http://localhost:14240/gsql/v1/loading-jobs/resume/jobId1'
```

Sample Response

```console
{"error": false,"message":"Successfully resumed loading job(s): [jobId1]."}
```

---

## Data source

### get a data source

`GET /gsql/v1/data-sources/{dsName}`

Get a data source.

#### Parameters:

None

#### Example:

Sample Request

```bash
curl -X GET "http://localhost:14240/gsql/v1/data-sources/k1"
```

Sample Response

```console
{"error":false,"message":"","results":{"name":"k1","type":"KAFKA","content":{"broker":"kafka-0.tigergraph.com","kafka_config":{"security.protocol":"SSL"}}}}
```

---

### get all data sources

`GET /gsql/v1/data-sources`

Get all data sources.

#### Parameters:

None

#### Example:

Sample Request

```bash
curl -X GET "http://localhost:14240/gsql/v1/data-sources"
```

Sample Response

```console
{"error":false,"message":"","results":[{"name":"s1","belongTo":"empty_graph","type":"S3","content":{"access.key":"AKIA6B6T6R52UU7XJ2NL","secret.key":"","type":"s3"},"isLocal":true},{"name":"s2","belongTo":"person_movie","type":"S3","content":{"access.key":"AKIA6B6T6R52UU7XJ2NL","secret.key":"","type":"s3"},"isLocal":true},{"name":"k1","type":"KAFKA","content":{"broker":"kafka-0.tigergraph.com","kafka_config":{"security.protocol":"SSL"}},"isLocal":false}]}
```

---

### update a data source

`PUT /gsql/v1/data-sources`

Update a data source .

#### Parameters:

| Name | Required | Description |
| --- | --- | --- |
| `graph` | no | the graph whose data source to update. If not provided, means to update a global data source. |

#### Example:

Sample Request

```bash
curl -X PUT 'Content-type: application/json' "http://localhost:14240/gsql/v1/data-sources/s5?graph=financialGraph" -d '{"name":"s5","config":{"type":"s3","access.key":"AKIA6B6T6R52UU7XJ2NL","secret.key":""}}'
```

Sample Response

```console
{"error":false,"message":"Data source s5 is created"}
```

---

### create data source

`POST /gsql/v1/data-sources`

Create a data source.

#### Parameters:

| Name | Required | Description |
| --- | --- | --- |
| `graph` | no | the graph whose data source to create. If not provided, means to create a global data source. |

#### Example:

Sample Request

```bash
curl -X POST 'Content-type: application/json' "http://localhost:14240/gsql/v1/data-sources?graph=financialGraph" -d '{"name":"s4","config":{"type":"s3","access.key":"AKIA6B6T6R52UU7XJ2NL","secret.key":""}}'
```

Sample Response

```console
{"error":false,"message":"Data source s4 is created"}
```

---

### drop one data source

`DELETE /gsql/v1/data-sources/{dsName}`

Drop one data source.

#### Parameters:

| Name | Required | Description |
| --- | --- | --- |
| `graph` | no | the graph whose data source to delete. If not provided, means to delete a global data source. |

#### Example:

Sample Request

```bash
curl -X DELETE 'Content-type: application/json' "http://localhost:14240/gsql/v1/data-sources/k1?graph=financialGraph" -d '{"error":false,"message":"Data source k1 is dropped."}'
```

Sample Response

```console
{"error":false,"message":"Data source k1 is dropped."}
```

---

### grant one data source

`POST /gsql/v1/data-sources/grant`

Grant one data source.

#### Parameters:

None

#### Example:

Sample Request

```bash
curl -X POST 'Content-type: application/json' "http://localhost:14240/gsql/v1/data-sources/grant" -d '{"graphs":["empty_graph","person_movie"],"datasource":"k1"}'
```

Sample Response

```console
{"error":false,"message":"Successfully grant datasource k1 to the graph(s) [empty_graph, person_movie]"}
```

---

### revoke datasource

`POST /gsql/v1/data-sources/revoke`

Revoke data source.

#### Parameters:

None

#### Example:

Sample Request

```bash
curl -X POST 'Content-type: text/plain' "http://localhost:14240/gsql/v1/data-sources/revoke" -d '{"graphs":["empty_graph","person_movie"],"datasource":"k1"}'
```

Sample Response

```console
{"error":false,"message":"Successfully revoke datasource k1 from graph(s) [empty_graph, person_movie]"}
```

---

### drop all data source

`DELETE /gsql/v1/data-sources/dropAll`

Drop all data source.

#### Parameters:

| Name | Required | Description |
| --- | --- | --- |
| `graph` | no | If given, will delete all the data sources used by this graph. otherwise will delete all the global data sources. |

#### Example:

Sample Request

```bash
curl -X DELETE 'Content-type: text/plain' "http://localhost:14240/gsql/v1/data-sources/dropAll"
```

Sample Response

```console
{"error":false,"message":"All data sources is dropped successfully."}
```

---

### get sample data from an S3 object

`POST /gsql/v1/sample-data`

Get the first N lines from an S3 object

#### Parameters:

None

#### Example:

Sample Request

```bash
curl -X POST 'Content-type: application/json' "http://localhost:14240/gsql/v1/sample-data" -d '
 {
  "graphName": "ldbc_snb",
  "dataSource": "adsafsfsfsfds",
  "type": "s3",
  "path": "s3a://gsql-sample-data/test-json/test.json",
  "dataFormat": "json",
  "parsing": {
    "fileFormat": "none",
    "eol": "\\n"
  },
  "filling": "N/A",
  "size": 10
}'
```

Sample Response

```console
{
    "error": false,
    "message": "",
    "results": {
        "data": [
            {
                "age": 40,
                "gender": "male",
                "name": "Tom",
                "state": "ca"
            },
            {
                "age": 34,
                "gender": "male",
                "name": "Dan",
                "state": "ny"
            },
            {
                "age": 25,
                "gender": "female",
                "name": "Jenny",
                "state": "tx"
            },
            [
                {
                    "age": 28,
                    "gender": "male",
                    "name": "Kevin",
                    "state": "az"
                },
                {
                    "age": 22,
                    "gender": "female",
                    "name": "Amily",
                    "state": "ca"
                },
                {
                    "age": 20,
                    "gender": "female",
                    "name": "Nancy",
                    "state": "ky"
                }
            ],
            {
                "age": 26,
                "gender": "male",
                "name": "Jack",
                "state": "fl"
            },
            {
                "age": 8,
                "gender": "male",
                "name": "a",
                "state": "OR"
            },
            {
                "age": 57,
                "gender": "male",
                "name": "aa",
                "state": "MA"
            },
            {
                "age": 25,
                "gender": "male",
                "name": "aaa",
                "state": "MI"
            },
            {
                "age": 71,
                "gender": "female",
                "name": "ab",
                "state": "WY"
            },
            {
                "age": 71,
                "gender": "female",
                "name": "abandoned",
                "state": "KS"
            }
        ],
        "header": [],
        "json": true
    }
}
```

---

### get all buckets of given S3 data source

`GET /gsql/v1/list-buckets/{s3Name}`

Get all buckets of given S3 data source.

#### Parameters:

None

#### Example:

Sample Request

```bash
curl -X GET 'Content-type: text/plain' "http://localhost:14240/gsql/v1/list-buckets/abcd"
```

Sample Response

```console
"error":false,"message":"","results":["acxiom2019","antifraudtg","aws-cloudtrail-logs-966275272565-4bde22f6","aws-glue-assets-966275272565-us-east-1","aws-logs-966275272565-us-east-1","bofa-louvain","ces-bucket-2","ces-neptune-bucket","ces-new-bucket","cf-templates-58ygac5qoly7-us-east-1","config-bucket-966275272565","databricks-workspace-stack-aa423-lambdazipsbucket-xjxhu6ikq892","databricks-workspace-stack-f31e4-bucket","databricks-workspace-stack-f31e4-lambdazipsbucket-ucd8ilhr3buv","databricks-workspace-stack-lambdazipsbucket-1qcpzmo9f4qzv","databricks-workspace-stack-lambdazipsbucket-1tycaofagn975","db-0cb8f9da9d4e67f9345947c4c54a5c3e-s3-root-bucket","db-81dc2edb4436079cea7c8c522f2ca24c-s3-root-bucket","db-ed2852b62420a6b838035944365a583a-s3-root-bucket","docker-image-store","docker-registry-backup","faerskit","faq.graphtiger.com","fareshealthcare","files.graphtiger.com","finfraud-demo-files","graphsql","graphsql-ctrip","graphsql-download","graphsql-elb-log","graphsql-eric-elb-log","graphsql-s3download","graphsql-test","graphsql-testdrive","graphsql-web","graphsql-xyz","graphsql-yeepay","graphstudio-customerportal","graphstudio-s3-e2e-test","graphstudio-sample-data-e2e-test","gsql-sample-data","kafka-connector-experiment","ldbc1","like-elb-test","litong","loading-test","merklescience","movie-rec-demo","pmitigergraph","presalesdocs","presalestg","racsftp","release-download-access-log","release-package-stats","release.graphtiger.com","renmaitong","rhfraud1","rik-bucket1","robb-tg-finfraud","robb-tgload-data","s3-import-test","s3-loading-test","se.training.deepdive","stevefuller-db","tango-test","test-graphstudio-bucket","test-s3import-el","test-website.graphtiger.com","tg-app-team","tg-isgs","tg-it-resource","tigergraph-aws-usage","tigergraph-benchmark-dataset","tigergraph-build-artifacts","tigergraph-cloudphysics","tigergraph-customer-support","tigergraph-development-artifects","tigergraph-download-hk","tigergraph-engineering-development-packages","tigergraph-fs-data","tigergraph-gle-prebuild","tigergraph-gui-prebuild-package","tigergraph-kafka-prebuild-package","tigergraph-mcafee-dlp","tigergraph-misc","tigergraph-release-download","tigergraph-release-prebuild","tigergraph-release-replica","tigergraph-temporary-files","tigergraph-test-dataset","tigergraph-testdrive-testdata","tigergraph-training","traininggsql","twitter-graph-benchmark","urbana-docker-ws","vladsynthea","xandrlog"]}
```

---

### get all files and directories under given S3 bucket path

`GET /gsql/v1/list-files/{s3Name}`

Get all files and directories under given S3 bucket path.

#### Parameters:

| Name | Required | Description |
| --- | --- | --- |
| `path` | no | Uri of the data source. If not provide, list files under `/` |

#### Example:

Sample Request

```bash
curl -X GET 'Content-type: text/plain' "http://localhost:14240/gsql/v1/list-files/fl2323?path=s3a://import-test"
```

Sample Response

```console
{"error":false,"results":{"folders":["test-folder"],"files":["chinese.csv","movies.csv","ratings.csv","ratings.tar","ratings.tar.gz","ratings.zip","中文®初めまして.csv"]}}
```

---

### get schema information from a Snowflake data source

`GET /gsql/v1/metadata/data-sources/{dsName}`

Get schema information from a Snowflake data source.`{dsPath}` is the name of a previously created Snowflake data source object.

#### Query Parameters:

None

#### Example:

Sample Request

```bash
curl -X GET 'Content-type: text/plain' "http://localhost:14240/gsql/v1/metadata/data-sources/k1"
```

Sample Response

```console
{"error":false,"message":"","results":{"databaseName":"snowflake_db","schemaName":"snowflake_schema","tableNames":["COMMENT","PERSON","POST"],"tables":[{"columns":[{"name":"ID","nullable":true,"type":"NUMBER"},{"name":"CONTENT","nullable":true,"type":"VARCHAR"},{"name":"CREATIONDATE","nullable":true,"type":"VARCHAR"}],"name":"COMMENT"},{"columns":[{"name":"ID","nullable":true,"type":"NUMBER"},{"name":"FIRSTNAME","nullable":true,"type":"VARCHAR"},{"name":"LASTNAME","nullable":true,"type":"VARCHAR"}],"name":"PERSON"},{"columns":[{"name":"ID","nullable":true,"type":"NUMBER"},{"name":"CONTENT","nullable":true,"type":"VARCHAR"},{"name":"CREATIONDATE","nullable":true,"type":"VARCHAR"}],"name":"POST"}],"viewNames":["VIEW_PERSON_DETAILS"],"views":[{"columns":[{"name":"FULLNAME","nullable":true,"type":"VARCHAR"},{"name":"EMAIL","nullable":true,"type":"VARCHAR"}],"name":"VIEW_PERSON_DETAILS"}]}}
```

---

## Query

### install queries

`GET /gsql/v1/queries/install`

This api is used for installing queries

#### Parameters:

| Name | Required | Description |
| --- | --- | --- |
| `graph` | yes | which graph to install queries |
| `queries` | yes | query names(join with `,` separated); value `*` or `all` mean all the queries. |
| `flag` | no | Possible values:`-single`: Install the query in single gpr mode.`-force`: Force the installation of the query.`-legacy`: Install the query in UDF mode.`-debug`: Present results contains debug info.`-cost`: Present results contains performance consumption.`-single` and `-legacy` cannot be used together. The other options can be combined. |

#### Example:

Sample Request

```bash
curl -X GET -H "Content-type: text/plain" "http://localhost:14240/gsql/v1/queries/install?graph=financialGraph1&queries=q1,q2&flag=-single"
```

Sample Response

```console
{
"requestId": ": "121212121331",
"message": "Successfully submitted request",
"startTime":  "2024-07-07T23:17:06.831474Z"
}
```

---

### check query install status

`GET /gsql/v1/queries/install/{requestId}`

This api is used for checking query install status

#### Example:

Sample Request

```bash
curl -X GET -H "Content-type: text/plain" "http://localhost:14240/gsql/v1/queries/install/121212121331"
```

Sample Response

```console
{
"error":false,
"message":"Request 121212121331 is running",
"requestId" : "121212121331",
"startTime": "2024-07-07T23:17:06.831474Z"
}
```

---

### list query names

`GET /gsql/v1/queries`

Get all query names of a graph.

#### Example

Sample Request

```bash
curl -H 'Content-Type: application/json' -X GET 'http://localhost:14240/gsql/v1/quries?graph=financialGraph'
```

Sample Response

```console
{"error":false,"message":"","results":["query1","query2"]}
```

---

### create query

`POST /gsql/v1/queries`

Create a query.

#### Parameters:

| Name | Required | Description |
| --- | --- | --- |
| `graph` | yes | the query created under which graph |

#### Example

Sample Request

```bash
curl -H 'Content-Type: text/plain' -X POST 'http://localhost:14240/gsql/v1/queries?graph=financialGraph'  -d 'create query q1 {...}'
```

Sample Response

```console
{"error":false,"message":"Successfully created queries: [q1].\n"}
```

---

### drop query

`DELETE /gsql/v1/queries`

Drop quries.

#### Parameters:

| Name | Required | Description |
| --- | --- | --- |
| `query` | yes | the queries to be dropped |
| `graph` | yes | the queries dropped under which graph |

#### Example

Sample Request

```bash
curl -H 'Content-Type: application/json' -X DELETE 'http://localhost:14240/gsql/v1/queries?query=q1&graph=financialGraph'
```

Sample Response

```console
{"failedToDrop":[],"dropped":["q1"],"error":false,"message":""}
```

---

### get query content

`GET /gsql/v1/queries/{queryName}`

This endpoint is to get the content of a query by its name. Please note that calling this endpoint needs to set 'Content-Type: application/json' in header.

#### Parameters:

| Name | Required | Description |
| --- | --- | --- |
| `queryName` | yes | the content of which query |
| `graph` | yes | the query under which graph |

#### Example

Sample Request

```bash
curl -H 'Content-Type: application/json' -X GET 'http://localhost:14240/gsql/v1/queries/q1?graph=financialGraph
```

Sample Response

```console
{"queryContent":"CREATE QUERY q1() { print 1;}","name":"test","syntax":"GSQL v2","error":false,"message":"","status":"VALID"}
```

---

## Comparing the RESTPP and GSQL query endpoints

TigerGraph provides two endpoints for running installed queries:

* [RESTPP endpoint](https://www.tigergraph.com/docs/tigergraph-server/4.3/API/built-in-endpoints.md#_run_an_installed_query_post)
* [GSQL endpoint](https://www.tigergraph.com/docs/tigergraph-server/4.3/API/gsql-endpoints.md#_run_query)

Both endpoints execute installed queries and return the same results. They differ in endpoint format, supported HTTP methods, parameter formats, and how requests are processed internally.

| Feature | RESTPP endpoint | GSQL endpoint |
| --- | --- | --- |
| Endpoint | `/query/{graph_name}/{query_name}` | `/gsql/v1/queries/{query_name}` |
| HTTP method | `GET` or `POST` | `POST` |
| `VERTEX` and `SET<VERTEX>` parameter format | Uses the RESTPP parameter format. See [Query parameter Passing](https://www.tigergraph.com/docs/tigergraph-server/4.3/API/built-in-endpoints.md#_run_an_installed_query_post). | Uses the GSQL parameter format. See [Format for Parameters of Query Being Run](https://www.tigergraph.com/docs/tigergraph-server/4.3/API/gsql-endpoints.md#_format_for_parameters_of_query_being_run). |
| Query execution | Executes the installed query directly. | Internally invokes the RESTPP endpoint to execute the installed query. |

### run query

`POST /gsql/v1/queries/{queryName}`

The endpoint is used to run a query by its name.

> [!NOTE]
> This endpoint provides a standardized GSQL API for running installed queries. Internally, it forwards requests to the RESTPP endpoint `GET /restpp/query/{graph_name}/{query_name}` to execute the query.
> 
> Use this endpoint if you are working with the standardized GSQL API or want consistency with other GSQL endpoints. If your application does not require the standardized GSQL API, consider using the [RESTPP endpoint](https://www.tigergraph.com/docs/tigergraph-server/4.3/API/built-in-endpoints.md#_run_an_installed_query_get), which executes installed queries directly without the additional request forwarding.
> 
> For a comparison of the RESTPP and GSQL endpoints, including differences in parameter formats and request processing, see [Comparing the RESTPP and GSQL query endpoints](https://www.tigergraph.com/docs/tigergraph-server/4.3/API/gsql-endpoints.md#_comparing_the_restpp_and_gsql_query_endpoints).

#### Endpoint Parameters:

| Name | Required | Description |
| --- | --- | --- |
| `queryName` | yes | the query to run |

#### Format for Parameters of Query Being Run

To pass the input parameter values to the query being run, include a JSON name-value pair in the payload (body) of the endpoint with the name `"parameters"`.

The value of `"parameters"` is a JSON object containing a name-value pair for each parameter.

| Value Type | Value Format | Example of Name:Value Pair |
| --- | --- | --- |
| Primitive (e.g., string, numeric, Boolean) | _value_ | `"age": 25` |
| Vertex, type specified in query definition | _vertex\_id_ | `"v_source": "v34261"` |
| Vertex, type not specified in query definition | \[_vertex\_id_, _vertex\_type_\] | `"vset_target": ["v5933", "Person"]` |
| List/set/bag of values | JSON array: `[value, value, value]` | `"input": [3,4,2,2]` |
| Map of values | Divide the map in an ordered list of keys and a correspondingly ordered list of values: JSON object containing a `"valuelist"` object and a `"keylist"` object | `"input":{"keylist":[49,50], "valuelist":["Alaska","Hawaii"]}}` |

> [!NOTE]
> If you are passing parameters in the inline body/payload of a POST request, you may need to escape the quotation marks in the JSON structure, e.g.,
> 
> -d "{\"input\":[3,4,2,2]}"

#### Example

Sample Query:

```bash
CREATE QUERY paramEx(STRING name, INT age, SET<VERTEX> neighbors)
{ PRINT name, age, neighbors; }
```

Sample Request

```bash
curl -H 'Content-Type: application/json' -X POST 'http://localhost:14240/gsql/v1/queries/paramEx?graph=financialGraph
-d '{"diagnose":false,"denseMode":false,"allvertex":false,"asyncRun":false,
"parameters":{"name":"Fred", "age":35,
"neighbors":[["Mr. McFeely","Person"],["Daniel Tiger","Puppet"]]}}'
```

Sample Response

```console
{"error":false,"message":"","results":{"error":false,"message":"","version":{"schema":1,"edition":"enterprise","api":"v2"},"results":
["name":"Fred", "age":35,
"neighbors":["Mr. McFeely","Daniel Tiger"]]}}
```

---

### list running queries

`GET /gsql/v1/queries/listrunning`

This endpoint retrieves all currently running queries that the user has permission to view. It also includes a `hasRunning` field in the response. If there are running queries, even if the user does not have permission to view them, `hasRunning` will still be true.

#### Parameters:

| Name | Required | Description |
| --- | --- | --- |
| `graph` | no | If provided, shows running queries for the specified graph. If omitted, shows queries for all graphs the user has access to. |

#### Permissions:

* Requires **READ Query** privilege on the graph.
* If the user has **READ Query** on a specific query only (not the whole graph), the API still returns information about that query.

#### Example

Sample Request

```bash
curl -u user1:pwd123 'http://<tigergraph-host>:14240/gsql/v1/queries/listrunning?graph=graphName'
```

Sample Response

```console
{
   "error":false,
   "message":"",
   "hasRunning":true,
   "results":[
      {
         "requestid":"16973825.RESTPP_1_1.1750902900072.N",
         "expirationTime":"2025-06-26 10:25:00.72",
         "startTime":"2025-06-26 09:55:00.72",
         "user":"user1",
         "url":"/query/graph1/queryName",
         "elapsedTime":956793,
         "status":"running"
      },
      {
         "requestid":"16973826.RESTPP_1_2.1750902900073.N",
         "expirationTime":"2025-07-10 11:30:00.15",
         "startTime":"2025-07-10 11:00:00.15",
         "user":"user2",
         "url":"/query/graph2/queryName2",
         "elapsedTime":123456,
         "status":"running"
      }
   ]
}
```

---

### drop one query

`DELETE /gsql/v1/queries/{queryName}`

Drop a query by its name.

#### Parameters:

| Name | Required | Description |
| --- | --- | --- |
| `queryName` | yes | the query to drop |

#### Example

Sample Request

```bash
curl -H 'Content-Type: application/json' -X DELETE 'http://localhost:14240/gsql/v1/queries/q1?graph=financialGraph
```

Sample Response

```console
{"failedToDrop":[],"dropped":["q1"],"error":false,"message":""}
```

---

### interpret query

`POST /gsql/v1/queries/interpret`

Intepret query. Please note that calling this endpont need to set 'Content-Type: text/plain' in header.

For interpret query, we can declare workload queue in 2 ways:

* In the request header
* In the GSQL query definition

#### Parameters:

| Name | Required | Description |
| --- | --- | --- |
| `graph` | yes | the query interpreted under which graph |

#### Headers:

| Name | Required | Description |
| --- | --- | --- |
| `workload_queue_name` | optional | the workload queue name |

#### Example

Sample Request

```bash
curl -H 'Content-Type: text/plain' -X POST 'localhost:14240/gsql/v1/queries/interpret?p1=hello&p1=world' -d 'INTERPRET QUERY (SET<STRING> p1) FOR GRAPH financialGraph syntax v1 {  print p1; }'
```

Sample Response

```console
{"error":false,"message":"","version":{"schema":1,"edition":"enterprise","api":"v2"},"results":[{"p1":["hello","world"]}]}
```

Sample Request For Interpreting Anonymous Query Using Request Header

```bash
curl -X POST -H 'Workload-Queue: <workload_queue_name>' 'localhost:14240/gsql/v1/queries/interpret?p1=hello&p1=world' -d 'INTERPRET QUERY (SET<STRING> p1) FOR GRAPH financialGraph syntax v1 {  print p1; }'
```

Sample Request For Interpreting Anonymous Query Using GSQL Command

```bash
curl -X POST 'localhost:14240/gsql/v1/queries/interpret?p1=hello&p1=world' -d 'INTERPRET QUERY -QUEUE <workload_queue_name> (SET<STRING> p1) FOR GRAPH financialGraph syntax v1 {  print p1; }'
```

---

### get query info

`GET /gsql/v1/queries/info`

Get the query's information.

#### Parameters:

| Name | Required | Description |
| --- | --- | --- |
| `graph` | yes | the query under which graph |
| `query` | no | the query name |
| `status` | no | the query status |

#### Example

Sample Request

```bash
curl -H 'Content-Type: application/json' -X GET 'localhost:14240/gsql/v1/queries/info?graph=financialGraph'
```

Sample Response

```console
{"error":false,"message":"","results":[{"graphUpdate":false,"installed":true,"endpoint":{"query":{"financialGraph":{"q1":{"GET/POST":{"graphUpdate":false,"summary":"This is query entrance","readDataList":{},"alternative_endpoint":"/query/q1","graph_name":"financialGraph","needReadRole":false,"executeGranted":false,"updateDataList":{},"enabled":true,"target":"GPE","deleteDataList":{},"libudf":"libudf-financialGraph-1","payload":[{"rule":"AS_JSON"},{"rule":"AS_QUERY_STRING"}],"function":"queryDispatcher","needCurrentRoles":false,"createDataList":{},"action":"query","executorList":[],"parameters":{"query":{"default":"q1","type":"STRING"}}}}}}},"code":"create query q1(){ print 1;}","callerQueries":[],"isACLSpecified":false,"name":"q1","syntax":"GSQL v2","installing":false,"enabled":true,"isHidden":false,"status":"VALID"}]}
```

---

### get query signature

`GET /gsql/v1/queries/signature`

Get query's signature by its name.

#### Parameters:

| Name | Required | Description |
| --- | --- | --- |
| `graph` | yes | the query under which graph |
| `queryName` | no | the query name to get query signature |
| `interpret` | no | default: false, false means the query in compiled mode and true means the query in interpret mode |

#### Example

Sample Request

```bash
curl -H 'Content-Type: text/plain' -X GET 'localhost:14240/gsql/v1/queries/signature?queryName=q1&graph=financialGraph'
```

Sample Response

```console
{"output":[{"1":"int"}],"input":[],"queryname":"q1","error":false,"message":"","version":{"schema":0,"edition":"ENTERPRISE_EDITION","api":"V2"}}
```

---

### query semantic check

`POST /gsql/v1/internal/check/query`

Perform a semantic check of a query.

#### Example

Sample Request

```bash
curl -H 'Content-Type: application/json' -X POST 'localhost:14240/gsql/v1/internal/check/query' -d ' {"code":""}'
```

Sample Response

```console
{"warnings":[],"errors":[]}
```

---

## Template query

### get all package names

`GET /gsql/v1/packages`

Get all package names.

#### Example

Sample Request

```bash
curl -H 'Content-Type: application/json' -X GET 'localhost:14240/gsql/v1/packages
```

Sample Response

```console
{"error":false,"message":"","results":["gds","gds.community"]}
```

---

### get package content

`GET /gsql/v1/package/{packageName}`

Get package by its name.

#### Example

Sample Request

```bash
curl -H 'Content-Type: application/json' -X GET 'localhost:14240/gsql/v1/packages/gds.community
```

Sample Response

```console
{"error":false,"message":"","results":{"fullPackageName":"gds.community","functions":[],"templateQueries":["printVertex"],"subpackageNames":[]}}
```

---

### create package

`POST /gsql/v1/package/{packageName}`

Create package.

#### Example

Sample Request

```bash
curl -H 'Content-Type: text/plain' -X POST 'localhost:14240/gsql/v1/packages/gds.commumity1
```

Sample Response

```console
{"error":false,"message":"Successfully created package: [gds.community1]."}
```

---

### drop package

`DELETE /gsql/v1/package/{packageName}`

Drop package by its name.

#### Example

Sample Request

```bash
curl -X DELETE 'localhost:14240/gsql/v1/packages/gds.commumity1
```

Sample Response

```console
{"error":false,"message":"Successfully dropped package: [gds.community1]."}
```

---

### create function

`POST /gsql/v1/package/function`

Create function

#### Example

Sample Request

```bash
curl -H 'Content-Type: text/plain' -X POST 'localhost:14240/gsql/v1/packages/function -d 'create function gds.community.func1 {<content>}'
```

Sample Response

```console
{"error":false,"message":"Successfully created function: [gds.community.func1]."}
```

---

### delete function

`DELETE /gsql/v1/package/{functionName}`

Delete function by its name.

#### Example

Sample Request

```bash
curl -X DELETE 'localhost:14240/gsql/v1/packages/function/gds.community.func1'
```

Sample Response

```console
{"error":false,"message":"Successfully dropped function: [gds.community.func1]."}
```

---

### create template query

`POST /gsql/v1/package/template`

Create template query.

#### Example

Sample Request

```bash
curl -H 'Content-Type: text/plain' -X POST 'localhost:14240/gsql/v1/packages/template' -d 'create template query gds.community.templateQuery1 {<content>}'
```

Sample Response

```console
{"error":false,"message":"Successfully created template query: [gds.community.templateQuery1]."}
```

---

### drop template query

`DELETE /gsql/v1/package/template/{queryName}`

Drop template query.

#### Example

Sample Request

```bash
curl -X DELETE 'localhost:14240/gsql/v1/packages/template/gds.community.templateQuery1'
```

Sample Response

```console
{"error":false,"message":"Successfully dropped template query: [gds.community.templateQuery1]."}
```

---

### import package

`POST /gsql/v1/package/import/{packageName}`

Import package.

#### Example

Sample Request

```bash
curl -X POST 'localhost:14240/gsql/v1/packages/import/pkg'
```

Sample Response

```console
{"error":false,"message":"Successfully import package pkg."}
```

---

### call template query

`POST /gsql/v1/library/{functionName}`

Call template query.

#### Parameters:

| Name | Required | Description |
| --- | --- | --- |
| `graph` | yes | the function under which graph |
| `functionName` | yes | the function name to call |

#### Example

Sample Request

```bash
curl -H 'Content-Type: application/json' -X POST 'localhost:14240/gsql/v1/library/gds_community_printVertex_0000000000?graph=financialGraph' -d '{parameters: {"vertex": ""}}'
```

Sample Response

```console
{"generatedQueryName":"gds_community_printVertex_0000000000","error":false,"message":"","results":{"error":false,"message":"","version":{"schema":1,"edition":"enterprise","api":"v2"},"results":[{"a":"3"}]}}
```

---

### get template query info

`GET /gsql/v1/library/{functionName}`

Get template query's information.

#### Parameters:

| Name | Required | Description |
| --- | --- | --- |
| `functionName` | yes | the function name of the tempalte query |
| `isRegularExpression` | no | deafult: false, true means using the regex pattern to match function name |

#### Example

Sample Request

```bash
curl -H 'Content-Type: application/json' -X GET 'localhost:14240/gsql/v1/library/printVertex'
```

Sample Response

```console
{"error":false,"message":"","results":[{"query":"CREATE template QUERY gds.community.printVertex(vertex a) SYNTAX V1 {\n  print a;\n}","name":"printVertex","params":{"a":{"id_type":"$a.type","type":"STRING","is_id":"true","min_count":0},"a.type":{"type":"STRING","min_count":0}}}]}
```

---

## Database Utilities

### generic endpoint to execute any GSQL command

`POST /gsql/v1/statements`

Execute any GSQL command asynchronously or synchronously.

#### Parameters:

| Name | Required | Description |
| --- | --- | --- |
| `async` | no | default: false; run the request asynchronously if true, otherwise run the request synchronously. |
| `timeout` | no | default: 0; the request will be aborted if not finished in timeout seconds. A value of 0 means the request will never time out. |

#### Example:

Sample Request

```bash
curl -X POST -H "content-type: text/plain" "http://localhost:14240/gsql/v1/statements" -d 'ls'
```

Sample Response

```console
---- Global vertices, edges, and all graphs
Vertex Types:
Edge Types:

Graphs:
Jobs:


JSON API version: v2
Syntax version: v2
```

---

### check status of asynchronous request with requestId

`GET /gsql/v1/statements/{requestId}`

Check status of asynchronous request with requestId.

#### Parameters:

None

#### Example:

Sample Request

```bash
curl -X GET -H "content-type: application/json" "http://localhost:14240/gsql/v1/statements/00000000006.317280417"
```

Sample Response

```console
{
"endTime":"2024-08-08T13:16:10.038174Z",
"error":false,
"message":"Request 00000000006.317280417 is finished with status SUCCESS",
"results":"---- Global vertices, edges, and all graphs\nVertex Types: \nEdge Types: \n\n\nGraphs: \nJobs: \n\n\n\n\nJSON API version: v2 \nSyntax version: v2\n"
}
```

---

### cancel an asynchronous request with requestId

`PUT /gsql/v1/statements/{requestId}/cancel`

Cancel an asynchronous request with requestId.

#### Parameters:

None

#### Example:

Sample Request

```bash
curl -X PUT -H "content-type: application/json" "http://localhost:14240/gsql/v1/statements/00000000006.317280417/cancel"
```

Sample Response

```console
{
"error":false,
"message":"Successfully aborted request 00000000006.317280417",
}
```

---

### recover gdict catalog

`POST /gsql/v1/schema/recover`

Recover catalog.

#### Parameters:

None

#### Example:

Sample Request

```bash
curl -X POST -H "content-type: text/plain" "http://localhost:14240/gsql/v1/schema/recover"
```

Sample Response

```console
{"error":false,"message":"Recover schema succeed!"}
```

---

### validate graph schema

`POST /gsql/v1/schema/check`

Check that a schema is valid.

#### Parameters:

None

#### Example:

Sample Request

```bash
curl -X POST -H "content-type: text/plain" "http://localhost:14240/gsql/v1/schema/check"
```

Sample Response

```console
{"error":false,"message":"Schema Check succeeded."}
```

---

### clear graph store

`GET /gsql/v1/clear-store`

This endpoint permanently deletes all the data out of the graph store (database), for all graphs. It does not delete the database schema, nor does it delete queries or loading jobs. It is equivalent to the GSQL command [CLEAR GRAPH STORE](https://www.tigergraph.com/docs/gsql-ref/4.3/ddl-and-loading/running-a-loading-job.md#_clear_graph_store).

> [!NOTE]
> This operation is not reversible. The deleted data cannot be recovered.

#### Example:

Sample Request

```bash
curl -H 'Content-Type: application/json' -X GET 'http://localhost:14240/gsql/v1/clear-store'
```

Sample Response

```console
{"error":false,"message":"Successfully cleared graph store."}
```

---

### get gsql version

`GET /gsql/v1/version`

This endpoint used for get the gsql version infomation.

#### Parameters:

| Name | Required | Description |
| --- | --- | --- |
| `verbose` | no | `bool` type, `true` will print detail info. |

#### Example:

Sample Request

```bash
curl -H 'Content-Type: text/plain' -X GET 'http://localhost:14240/gsql/v1/version?verbose=true'
```

Sample Response

```console
GSQL version: GLE-7162
GSQL commit number: 3f46585895039eb41a460e87e6b8f15eef224800
GSQL commit date: 2024-07-26 08:56:11 +0800
Copyright (c) 2014-2024 TigerGraph. All rights reserved.
This product is protected by U.S. and international copyright and intellectual property laws.
```

---

### drop all

`GET /gsql/v1/drop-all`

Drop all.

> [!NOTE]
> This operation is not reversible. The deleted data cannot be recovered.

#### Example

Sample Request

```bash
curl -H 'Content-Type: application/json' -X GET 'localhost:14240/gsql/v1/drop-all'
```

Sample Response

```console
{"error":false,"message":"Successfully dropped all."}
```

---

### graph export

`POST /gsql/v1/db-export`

Export database.

#### Example

Sample Request

```bash
curl -H 'Content-Type: application/json' -X POST 'localhost:14240/gsql/v1/db-export' -d  '{"path":"pass","graphNames":["*"],"schema":false,"template":false,"data":false,"users":false,"password":"password","separator":"\u001d","eol":"\u001c"}'
```

Sample Response

```console
{"error":false,"message":"Successfully exported database."}
```

---

### graph import

`POST /gsql/v1/db-import`

Import database.

#### Example

Sample Request

```bash
curl -H 'Content-Type: application/json' -X POST 'localhost:14240/gsql/v1/db-import' -d  '{"path":"pass","graphNames":["*"],"keepUsers":false,"password":"password"}'
```

Sample Response

```console
{"error":false,"message":"Successfully imported database."}
```

---

## Security

### create new JWT token

`POST /gsql/v1/tokens`

Create a new JWT token.

#### Payload:

| Name | Required | Description |
| --- | --- | --- |
| `secret` | no | the secret denotes the user |
| `graph` | no | the graph the token created for |
| `lifetime` | no | default: one week, the duration time of the token |

#### Example

Sample Request

```bash
curl -H 'Content-Type: application/json' -X POST 'localhost:14240/gsql/v1/tokens' -d "{\"secret\": \"j2qho3smncbk4g5cg4airige8up5bqn2\"}"
```

Sample Response

```console
{"expiration":"Fri Dec 20 09:07:39 UTC 2024","error":false,"message":"Generate new JWT token successfully.","token":"eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJ0aWdlcmdyYXBoIiwiaWF0IjoxNzM0MDgwODU0LCJleHAiOjE3MzQ2ODU2NTksImlzcyI6IlRpZ2VyR3JhcGgifQ.1Qrgj2I90WL4Xo8cMaXrmyOQmqhgNz1rES0hJu7H3mg"}
```

---

### drop JWT tokens

`DELETE /gsql/v1/tokens`

Drop specific a list of tokens.

#### Parameters:

| Name | Required | Description |
| --- | --- | --- |
| `clear` | no | default: false, true means clear out the current block list. |

#### Example

Sample Request

```bash
curl -H 'Content-Type: application/json' -X DELETE 'localhost:14240/gsql/v1/tokens' -d '{"tokens": "eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJ0aWdlcmdyYXBoIiwiaWF0IjoxNzM0MDgwODU0LCJleHAiOjE3MzQ2ODU2NTksImlzcyI6IlRpZ2VyR3JhcGgifQ.1Qrgj2I90WL4Xo8cMaXrmyOQmqhgNz1rES0hJu7H3mg"}'
```

Sample Response

```console
{"error": false, "message": "Successfully dropped the specified JWT tokens"}
```

---

### check JWT token

`POST /gsql/v1/tokens/check`

Check JWT token is valid or not.

#### Example

Sample Request

```bash
curl -H 'Content-Type: application/json' -X POST 'localhost:14240/gsql/v1/tokens/check' -d '{"token": "eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJ0aWdlcmdyYXBoIiwiaWF0IjoxNzM0MDgwODU0LCJleHAiOjE3MzQ2ODU2NTksImlzcyI6IlRpZ2VyR3JhcGgifQ.1Qrgj2I90WL4Xo8cMaXrmyOQmqhgNz1rES0hJu7H3mg"}'
```

Sample Response

```console
{"error":false,"message":"The token eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJ0aWdlcmdyYXBoIiwiaWF0IjoxNzM0MDgwODU0LCJleHAiOjE3MzQ2ODU2NTksImlzcyI6IlRpZ2VyR3JhcGgifQ.1Qrgj2I90WL4Xo8cMaXrmyOQmqhgNz1rES0hJu7H3mg verification succeed."}
```

---

### create secret

`POST /gsql/v1/secrets`

Create a secret.

#### Parameters:

| Name | Required | Description |
| --- | --- | --- |
| `userName` | no | the user the secret created for. The default user is the logged-in user if not specified. |
| `alias` | no | the alias of the secret created. |

#### Example

Sample Request

```bash
curl -H 'Content-Type: application/json' -X POST 'localhost:14240/gsql/v1/secrets?alias=s1'
```

Sample Response

```console
{"error":false,"message":"","results":{"alias":"s1",
 "created_at":1784594193869,
 "value":"59ccqdlqmkfcqjl99u2jv4qt2telmeoj"}}
```

---

### show secrets

`GET /gsql/v1/secrets`

Show secrets for the user.

#### Parameters:

| Name | Required | Description |
| --- | --- | --- |
| `userName` | no | the user who wants to show the secrets. The default user is the logged-in user if not specified. |

#### Example

Sample Request

```bash
curl -H 'Content-Type: application/json' -X GET 'localhost:14240/gsql/v1/secrets'
```

Sample Response

```console
{"error":false,"message":"","results":{"alias":"s1",
 "created_at":1784765075234,
 "value":"59ccqdlqmkfcqjl99u2jv4qt2telmeoj"}}
```

---

### delete secrets

`DELETE /gsql/v1/secrets`

Delete the secrets of the user.

#### Parameters:

| Name | Required | Description |
| --- | --- | --- |
| `userName` | no | the user who wants to delete the secrets. The default user is the logged-in user if not specified. |

#### Example

Sample Request

```bash
curl -H 'Content-Type: application/json' -X DELETE 'localhost:14240/gsql/v1/secrets' -d '{"secrets":[$secret1,$secret2]}'
```

Sample Response

```console
{"error":false,"message":"Successfully removed the secrets for user tigergraph."}
```

---

### get secret by alias

`GET /gsql/v1/secrets/{alias}`

Get the secrets by its alias name.

#### Parameters:

| Name | Required | Description |
| --- | --- | --- |
| `userName` | no | the user who wants to get the secret. The default user is the logged-in user if not specified. |

#### Example

Sample Request

```bash
curl -H 'Content-Type: application/json' -X GET 'localhost:14240/gsql/v1/secrets/s2'
```

Sample Response

```console
{"error":false,"message":"","results":{"alias":"s2",
 "created_at":1784734930512,
 "value":"g2ea27q79tes6nsark3k3ecp718rp4ej"}}
```

---

### drop secret by alias

`DELETE /gsql/v1/secrets/{alias}`

Delete the secret of the user by its alias name.

#### Parameters:

| Name | Required | Description |
| --- | --- | --- |
| `userName` | no | the user who wants to delete the secret. The default user is the logged-in user if not specified. |

#### Example

Sample Request

```bash
curl -H 'Content-Type: application/json' -X DELETE 'localhost:14240/gsql/v1/secrets/s2'
```

Sample Response

```console
{"error":false,"message":"Successfully removed the secrets for user tigergraph."}
```

---

### retrieve a group by id using gsql format

`GET /gsql/v1/groups/{id}`

Retrieve a group by id response scim format or gsql format JSON.

#### Parameters:

None

#### Example:

Sample Request

```bash
curl -X GET "http://localhost:14240/gsql/v1/groups/g1"
```

Sample Response

```console
{"error":false,"message":"","results":{"lastSuccessLogin":"Thu Aug 08 16:31:56 HKT 2024","privileges":{},"nextValidLogin":"Thu Aug 08 16:31:56 HKT 2024","roles":{},"failedAttempts":0,"members":[],"name":"g1","rule":"group=th-department","disabled":false,"isSuperUser":false,"showAlterPasswordWarning":false,"secrets":[]}}
```

---

### retrieve groups using gsql format

`GET /gsql/v1/groups`

Retrieve groups response gsql format JSON.

#### Parameters:

| Name | Required | Description |
| --- | --- | --- |
| `graph` | no | If the graph is not specified and the current user has global READ\_PROXYGROUP privilege, they can see all proxy groups. Otherwise, no proxy group information can be accessed. If the graph is specified and the current user has local READ\_PROXYGROUP privilege for this graph, they can only view the proxy groups on this specific graph. |

#### Example:

Sample Request

```bash
curl -X GET "Content-type: text/plain" "http://localhost:14240/gsql/v1/groups"
```

Sample Response

```console
{"error":false,"results":[{"lastSuccessLogin":"Tue Jul 02 17:07:50 HKT 2024","privileges":{},"nextValidLogin":"Tue Jul 02 17:07:50 HKT 2024","roles":{},"failedAttempts":0,"members":[],"name":"g1","rule":"group=tech-department","disabled":false,"isSuperUser":false,"showAlterPasswordWarning":false,"secrets":[]},{"lastSuccessLogin":"Tue Jul 02 17:07:50 HKT 2024","privileges":{},"nextValidLogin":"Tue Jul 02 17:07:50 HKT 2024","roles":{},"failedAttempts":0,"members":[],"name":"g2","rule":"group=tech-department","disabled":false,"isSuperUser":false,"showAlterPasswordWarning":false,"secrets":[]}]}
```

---

### create a group using gsql format

`POST /gsql/v1/groups`

Create a group using gsql format.

#### Parameters:

None

#### Example:

Sample Request

```bash
curl -X POST "Content-type: application/json" "http://localhost:14240/gsql/v1/groups" -d '{"groupName":"g4","proxyRule":"group=tech-department"}'
```

Sample Response

```console
{"error":false,"message":"Successfully created group g4","results":{"lastSuccessLogin":"Tue Jul 02 17:32:40 HKT 2024","privileges":{},"nextValidLogin":"Tue Jul 02 17:32:40 HKT 2024","roles":{},"failedAttempts":0,"members":[],"name":"g4","rule":"group=tech-department","disabled":false,"isSuperUser":false,"showAlterPasswordWarning":false,"secrets":[]}}
```

---

### update a group using gsql format

`PUT /gsql/v1/groups`

Update a group.

#### Parameters:

None

#### Example:

Sample Request

```bash
curl -X PUT "Content-type: application/json" "http://localhost:14240/gsql/v1/groups" -d '{"name": "g1", "rule": ""group=tech-department""}'
```

Sample Response

```console
{"error": true, "message": "Successfully change the proxy rule for group g1"}
```

---

### drop one group by name using gsql format

`DELETE /gsql/v1/groups/{id}`

Drop one group by name.

#### Parameters:

None

#### Example:

Sample Request

```bash
curl -X DELETE "Content-type: application/json" "http://localhost:14240/gsql/v1/groups/g1"
```

Sample Response

```console
{"error":false,"message":"Successfully dropped group g1"}
```

---

### drop groups using gsql format

`POST /gsql/v1/groups`

Drop groups.

#### Parameters:

| Name | Required | Description |
| --- | --- | --- |
| `action` | no | The default value is `create`. Possible values are `create` and `delete`. `Delete` indicates dropping groups, while `create` indicates creating groups. |

#### Example:

Sample Request

```bash
curl -X POST "Content-type: application/json" "http://localhost:14240/gsql/v1/groups?action=delete" -d '{"groupNames":["g1"]}'
```

Sample Response

```console
{"error":false,"message":"Successfully dropped groups: [g1]"}
```

---

### retrieve a user by id using gsql format

`GET /gsql/v1/users/{id}`

Retrieve a user by id respond gsql format.

#### Parameters:

None

#### Example:

Sample Request

```bash
curl -X GET "http://localhost:14240/gsql/v1/users/u1"
```

Sample Response

```console
{"error":false,"message":"","results":{"lastSuccessLogin":"Thu Aug 08 16:51:23 HKT 2024","privileges":{"recommend":{"privileges":[]}},"nextValidLogin":"Thu Aug 08 16:51:23 HKT 2024","roles":{"recommend":["r1"]},"failedAttempts":0,"name":"u1","disabled":false,"isSuperUser":false,"showAlterPasswordWarning":false,"secrets":[]}}
```

---

### update an user using gsql format

`PUT /gsql/v1/users`

Update a user.

#### Parameters:

None

#### Example:

Sample Request

```bash
curl -X PUT -H "Content-type: application/json" "http://localhost:14240/gsql/v1/users"  -d '{"name": "tigergraph", "password": "123"}'
```

Sample Response

```console
{"error": false, "message": "Successfully updated user tigergraph"}
```

---

### drop users for gsql format

`POST /gsql/v1/users`

Drop users.

#### Parameters:

| Name | Required | Description |
| --- | --- | --- |
| `action` | no | default: `create`. Possible values: `create`, `delete`. `delete` indicates to drop users; `create` indicates to create users. Here set the value `delete`. |

#### Example:

Sample Request

```bash
curl -X POST -H "Content-type: application/json" "http://localhost:14240/gsql/v1/users?action=delete"  -d ' {"userNames":["u1"]}'
```

Sample Response

```console
{"error":false,"message":"Successfully dropped users: [u1]"}
```

---

### drop a user using gsql format

`DELETE /gsql/v1/users/{id}`

Drop a user.

#### Parameters:

None

#### Example:

Sample Request

```bash
curl -X DELETE -H "Content-type: application/json" "http://localhost:14240/gsql/v1/users/u1"
```

Sample Response

```console
{"error":false,"message":"Successfully dropped user u1"}
```

---

### create a user using gsql format

`POST /gsql/v1/users`

Create a user using gsql format.

#### Parameters:

None

#### Example:

Sample Request

```bash
curl -X POST -H "Content-type: application/json" "http://localhost:14240/gsql/v1/users" -d ' {"password":"tiger123","username":"user2"}'
```

Sample Response

```console
{"error":false,"message":"Successfully created user user2"}
```

---

### Create a proxy user

`POST /gsql/v1/proxyusers`

Create a proxy user for SSO authentication. Proxy users do not have local passwords and cannot authenticate using username/password.

#### Required privilege

`WRITE_USER`

#### Parameters

None

#### Request body

| Field | Required | Description |
| --- | --- | --- |
| username | Yes | Proxy user name. Must match the SSO identity. |
| auth\_methods | No | Allowed SSO authentication methods (`KERBEROS`, `OIDC`, `SAML`). If specified, the proxy user can log in only using these methods. If not specified, all supported SSO methods (`KERBEROS`, `OIDC`, `SAML`) are allowed. This field accepts a JSON array, allowing multiple authentication methods. |
| roles | No | Roles to grant to the proxy user after creation. |

#### Example

Sample Request

```bash
curl -u user1:pwd123
-X POST "http://localhost:14240/gsql/v1/proxyusers
"
-H "Content-Type: application/json"
-d '{
"username": "qatest",
"auth_methods": ["OIDC", "SAML"],
"roles": ["role1", "role2"]
}'
```

Sample Response

```console
{
  "error": false,
  "message": "Successfully created proxy user qatest"
}
```

### Delete a proxy user

`DELETE /gsql/v1/proxyusers/{username}`

Delete an existing proxy user.

#### Required privilege

`WRITE_USER`

#### Parameters

None

#### Example

Sample Request

```bash
curl -u user1:pwd123 \
-X DELETE "http://localhost:14240/gsql/v1/proxyusers/test_user"
```

Sample Response

```console
{
  "error": false,
  "message": "Successfully deleted proxy user test_user"
}
```

### Retrieve proxy users

`GET /gsql/v1/proxyusers`

Retrieve all proxy users.

#### Required privilege

`READ_USER`

#### Parameters

None

#### Example

Sample Request

```bash
curl -u user1:pwd123 \
-X GET "http://localhost:14240/gsql/v1/proxyusers"
```

Sample Response

```console
{
  "error": false,
  "users": [
    {
      "name": "test_user",
      "roles": ["role1"],
      "authMethods": ["OIDC"],
      "groups": ["group1"]
    }
  ]
}
```

### Retrieve a single proxy user

`GET /gsql/v1/proxyusers/{username}`

Retrieve details of a specific proxy user.

#### Required privilege

`READ_USER` (unless requesting the current user)

#### Parameters

None

#### Example

Sample Request

```bash
curl -u user1:pwd123 \
-X GET "http://localhost:14240/gsql/v1/proxyusers/test_user"
```

Sample Response

```console
{
  "error": false,
  "name": "test_user",
  "roles": ["role1"],
  "authMethods": ["OIDC"],
  "groups": ["group1"],
  "disabled": false,
  "lastSuccessLogin": "Wed Nov 12 17:01:30 PST 2025"
}
```

### retrieve users using gsql format

`GET /gsql/v1/users`

Retrieve users response gsql format JSON.

#### Parameters:

| Name | Required | Description |
| --- | --- | --- |
| `graph` | no | If the graph is not provided and the current user has global READ\_USER privilege, they can view all users. Otherwise, no user information can be accessed. If the graph is provided, users with global READ\_USER privilege can view all users. If the current user holds local READ\_USER privilege for this graph, they can only see users with access to this specific graph. Otherwise, they can only view their own information if they have access to the graph. |

#### Example:

Sample Request

```bash
curl -X GET -H "Content-type: application/json" "http://localhost:14240/gsql/v1/users"
```

Sample Response

```console
{"error":false,"results":[{"lastSuccessLogin":"Wed Jul 03 15:26:33 HKT 2024","privileges":{"1":{"privileges":["READ_SCHEMA","WRITE_SCHEMA","READ_LOADINGJOB","EXECUTE_LOADINGJOB","WRITE_LOADINGJOB","CREATE_QUERY","WRITE_DATASOURCE","READ_ROLE","WRITE_ROLE","READ_USER","WRITE_USER","READ_PROXYGROUP","WRITE_PROXYGROUP","READ_FILE","WRITE_FILE","DROP_GRAPH","EXPORT_GRAPH","CLEAR_GRAPHSTORE","DROP_ALL","READ_DATA","CREATE_DATA","UPDATE_DATA","DELETE_DATA","APP_ACCESS_DATA","READ_POLICY","WRITE_POLICY","USE_FUNCTION","WRITE_FUNCTION","READ_WORKLOAD_QUEUE","WRITE_WORKLOAD_QUEUE"]},"recommend":{"privileges":[]}},"nextValidLogin":"Wed Jul 03 15:26:33 HKT 2024","roles":{"1":["superuser"],"recommend":["superuser"]},"failedAttempts":0,"name":"tigergraph","disabled":false,"isSuperUser":true,"showAlterPasswordWarning":false,"secrets":[]},{"lastSuccessLogin":"Wed Jul 03 15:26:33 HKT 2024","privileges":{"recommend":{"privileges":[]}},"nextValidLogin":"Wed Jul 03 15:26:33 HKT 2024","roles":{"recommend":["r1"]},"failedAttempts":0,"name":"u1","disabled":false,"isSuperUser":false,"showAlterPasswordWarning":false,"secrets":[]}]}
```

---

### show all privileges

`GET /gsql/v1/privileges`

List all built-in privileges.

#### Example:

Sample Request

```bash
curl -H 'Content-Type: application/json' -X GET "http://localhost:14240/gsql/v1/privileges"
```

Sample Response

```console
{"error":false,"message":"","results":[{"privilegeType":"GRAPH","privilege":"READ_SCHEMA"},{"privilegeType":"GRAPH","privilege":"WRITE_SCHEMA"},{"privilegeType":"GRAPH","privilege":"READ_LOADINGJOB"},{"privilegeType":"GRAPH","privilege":"EXECUTE_LOADINGJOB"},{"privilegeType":"GRAPH","privilege":"WRITE_LOADINGJOB"},{"privilegeType":"QUERY","privilege":"READ_QUERY"},{"privilegeType":"GRAPH","privilege":"CREATE_QUERY"},{"privilegeType":"QUERY","privilege":"UPDATE_QUERY"},{"privilegeType":"QUERY","privilege":"DROP_QUERY"},{"privilegeType":"QUERY","privilege":"INSTALL_QUERY"},{"privilegeType":"QUERY","privilege":"EXECUTE_QUERY"},{"privilegeType":"QUERY","privilege":"OWNER"},{"privilegeType":"GRAPH","privilege":"WRITE_DATASOURCE"},{"privilegeType":"GRAPH","privilege":"READ_ROLE"},{"privilegeType":"GRAPH","privilege":"WRITE_ROLE"},{"privilegeType":"GRAPH","privilege":"READ_USER"},{"privilegeType":"GLOBAL","privilege":"WRITE_USER"},{"privilegeType":"GRAPH","privilege":"READ_PROXYGROUP"},{"privilegeType":"GLOBAL","privilege":"WRITE_PROXYGROUP"},{"privilegeType":"GLOBAL","privilege":"READ_FILE"},{"privilegeType":"GLOBAL","privilege":"WRITE_FILE"},{"privilegeType":"GLOBAL","privilege":"DROP_GRAPH"},{"privilegeType":"GLOBAL","privilege":"EXPORT_GRAPH"},{"privilegeType":"GLOBAL","privilege":"CLEAR_GRAPHSTORE"},{"privilegeType":"GLOBAL","privilege":"DROP_ALL"},{"privilegeType":"GRAPH","privilege":"READ_DATA"},{"privilegeType":"GRAPH","privilege":"CREATE_DATA"},{"privilegeType":"GRAPH","privilege":"UPDATE_DATA"},{"privilegeType":"GRAPH","privilege":"DELETE_DATA"},{"privilegeType":"GRAPH","privilege":"APP_ACCESS_DATA"},{"privilegeType":"GRAPH","privilege":"READ_POLICY"},{"privilegeType":"GRAPH","privilege":"WRITE_POLICY"},{"privilegeType":"PACKAGE","privilege":"USE_FUNCTION"},{"privilegeType":"PACKAGE","privilege":"WRITE_FUNCTION"},{"privilegeType":"GLOBAL","privilege":"READ_WORKLOAD_QUEUE"},{"privilegeType":"GLOBAL","privilege":"WRITE_WORKLOAD_QUEUE"}]}
```

---

### grant privilege(s) to role(s)

`POST /gsql/v1/privileges/grant`

Grant RABC privileges to specific roles.

#### Parameters:

| Name | Required | Description |
| --- | --- | --- |
| `graph` | no | in which graph the privilege(s) should be granted, or grant privilege(s) on global level if the parameter is missing |

#### Example:

Sample Request

```bash
curl -H 'Content-Type: application/json' -X POST "http://localhost:14240/gsql/v1/privileges/grant?graph=financialGraph" -d "{"privileges":["READ_DATA", "CREATE_DATA", "UPDATE_DATA"], "vertexName": "Account", "roles":["r1", "r2"]}"
```

Sample Response

```console
{"error":false,"message":"The privileges \"CREATE, READ, UPDATE\" are successfully granted on \"VERTEX Account\" IN GRAPH recommend to role: r2\nThe privileges \"CREATE, READ, UPDATE\" are successfully granted on \"VERTEX Account\" IN GRAPH recommend to role: r1\n","results":[{"privileges":{"1":{"privileges":[]},"recommend":{"privileges":[],"childPermissions":{"user":{"privileges":["READ_DATA","CREATE_DATA","UPDATE_DATA"]}}}},"role":"r1"},{"privileges":{"recommend":{"privileges":[],"childPermissions":{"user":{"privileges":["READ_DATA","CREATE_DATA","UPDATE_DATA"]}}}},"role":"r2"}]}
```

---

### revoke privilege(s) from role(s)

`POST /gsql/v1/privileges/revoke`

Revoke RABC privileges from specific roles

#### Parameters:

| Name | Required | Description |
| --- | --- | --- |
| `graph` | no | in which graph the privilege(s) should be revoked, or revoke privilege(s) on global level if the parameter is missing |

#### Example:

Sample Request

```bash
curl -H 'Content-Type: application/json' -X POST "http://localhost:14240/gsql/v1/privileges/revoke?graph=financialGraph" -d "{"privileges":["READ_DATA", "CREATE_DATA", "UPDATE_DATA"], "vertexName": "Account", "roles":["r1", "r2"]}"
```

Sample Response

```console
{"error":false,"message":"The privileges \"CREATE, READ, UPDATE\" are successfully revoked on \"VERTEX Account\" IN GRAPH recommend from role: r2\nThe privileges \"CREATE, READ, UPDATE\" are successfully revoked on \"VERTEX Account\" IN GRAPH recommend from role: r1\n","results":[{"privileges":{"1":{"privileges":[]}},"role":"r1"},{"privileges":{},"role":"r2"}]}
```

---

### show all roles

`GET /gsql/v1/roles`

Call this endpoint to show all roles, including built-in roles and user defined roles.

#### Example:

Sample Request

```bash
curl -H 'Content-Type: application/json' -X GET "http://localhost:14240/gsql/v1/roles"
```

Sample Response

```console
{"error":false,"message":"","results":{"builtIn":{"global":["globalobserver","globaldesigner","superuser"],"local":["observer","queryreader","querywriter","designer","admin"]},"userDefinedRoles":{"1":["r1","r2","r3"],"recommend":["r4"]}}}
```

---

### Create roles

`POST /gsql/v1/roles`

#### Parameters:

| Name | Required | Description |
| --- | --- | --- |
| `graph` | no | in which graph to create local roles, or create global roles if the parameter is missing |

#### Example:

Sample Request

```bash
curl -H 'Content-Type: application/json' -X POST "http://localhost:14240/gsql/v1/roles?graph=financialGraph" -d "{"roles":["r1", "r2"]}"
```

Sample Response

```console
{"error":false,"message":"","results":"Successfully created local roles on graph 'financialGraph': [r1, r2]."}
```

---

### Delete roles

`DELETE /gsql/v1/roles`

#### Parameters:

| Name | Required | Description |
| --- | --- | --- |
| `graph` | no | in which graph to delete local roles, or delete global roles if the parameter is missing |
| `roles` | yes | roles to delete |

#### Example:

Sample Request

```bash
curl -H 'Content-Type: application/json' -X DELETE "http://localhost:14240/gsql/v1/roles?graph=financialGraph&role=r1,r2"
```

Sample Response

```console
{"error":false,"message":"","results":"Successfully dropped roles: [r1, r2]."}
```

---

### show one role

`GET /gsql/v1/roles/{roleName}`

Call this endpoint to show the info of a specific role.

#### Example:

Sample Request

```bash
curl -H 'Content-Type: application/json' -X GET "http://localhost:14240/gsql/v1/roles/r1"
```

Sample Response

```console
{"error":false,"message":"","results":{"Graph":"financialGraph","roleName":"r1","isGlobal":false,"rolePrivileges":{"financialGraph":{"privileges":["READ_DATA","CREATE_DATA"]}}}}
```

---

### delete one role

`DELETE /gsql/v1/roles/{roleName}`

Call this endpoint to delete a specific role.

#### Example:

Sample Request

```bash
curl -H 'Content-Type: application/json' -X DELETE "http://localhost:14240/gsql/v1/roles/r1"
```

Sample Response

```console
{"error":false,"message":"","results":"Successfully dropped roles: [r1]."}
```

---

### grant role(s) to user(s)

`POST /gsql/v1/roles/grant`

Grant roles to specific users

#### Parameters:

| Name | Required | Description |
| --- | --- | --- |
| `graph` | no | in which graph the role(s) should be granted, or grant role(s) on global level if the parameter is missing |

#### Example:

Sample Request

```bash
curl -H 'Content-Type: application/json' -X POST 'http://localhost:14240/gsql/v1/roles/grant?graph=financialGraph' -d '{"roles":["observer", "r1"], "users":["user1", "user2"]}'
```

Sample Response

```console
{"error":false,"message":"","results":"Successfully granted roles [observer, r1] on graph 'financialGraph' to users [user1, user2]."}
```

---

### revoke role(s) from user(s)

`POST /gsql/v1/roles/revoke`

Revoke roles from specific users

#### Parameters:

| Name | Required | Description |
| --- | --- | --- |
| `graph` | no | in which graph the role(s) should be revoked, or revoke role(s) on global level if the parameter is missing |

#### Example:

Sample Request

```bash
curl -H 'Content-Type: application/json' -X POST 'http://localhost:14240/gsql/v1/roles/revoke?graph=financialGraph' -d '{"roles":["observer", "r1"], "users":["user1", "user2"]}'
```

Sample Response

```console
{"error":false,"message":"","results":"Successfully revoked roles [observer, r1] on graph 'financialGraph' from users [user1, user2]."}
```

---

## SCIM APIs for users/groups

### retrieve a group by id using scim format

`GET /gsql/scim/v2/Groups/{id}`

Retrieve a group by id response scim format.

#### Parameters:

None

#### Example:

Sample Request

```bash
curl -X GET "http://localhost:14240/gsql/scim/v2/Groups/g2"
```

Sample Response

```console
{"displayName":"g2","meta":{"location":"/scim/v2/Groups/54ba8a0f-693c-4cf3-9c53-5caaa244049a","resourceType":"Group"},"members":[],"id":"54ba8a0f-693c-4cf3-9c53-5caaa244049a"}
```

---

### retrieve groups using scim format

`GET /gsql/scim/v2/Groups`

Retrieve groups response scim format.

#### Parameters:

| Name | Required | Description |
| --- | --- | --- |
| `filter` | no | The filter format should follow this structure: `displayName op {value} op2 displayName op {value}`. Here, `op` can be one of `eq`, `ne`, `co`, `sw`, `ew`, and `op2` can be either `and` or `or`. |
| `excludedAttributes` | no | Specifies attributes to be excluded. Currently supports only `members`. |

#### Example:

Sample Request

```bash
curl -X GET -H "Content-type: text/plain" "http://localhost:14240/gsql/scim/v2/Groups?excludedAttributes=members&filter=displayName%ne%20'g2'%20and%20displayName%20sw%20'g1'"
```

Sample Response

```console
{"totalResults":1,"startIndex":1,"itemsPerPage":100,"schemas":true,"Resources":[{"displayName":"g1","meta":{"location":"/scim/v2/Groups/0570fc42-79ea-427e-aa2e-2b53a0470163","resourceType":"Group"},"id":"0570fc42-79ea-427e-aa2e-2b53a0470163"}]}
```

---

### create a group using scim format

`POST /gsql/scim/v2/Groups`

Create a group using scim format.

#### Parameters:

None

#### Example:

Sample Request

```bash
curl -X POST "Content-type: application/json" "http://localhost:14240/gsql/scim/v2/Groups" -d '{"displayName":"scimG3","schemas":"[\"urn:ietf:params:scim:schemas:core:2.0:Group\"]","members":[{"display":"user3"},{"value":"user4"}]}'
```

Sample Response

```console
{"displayName":"scimG3","meta":{"location":"/scim/v2/Groups/706d0ad6-2165-4190-8512-de5abfd06988","resourceType":"Group"},"members":[{"display":"user3","type":"User","value":"16c1e6cc-3b2a-4d57-9a2e-fb55a5d14804"},{"display":"user4","type":"User","value":"457b9982-d5fb-4ad6-b50a-266919bf0c16"}],"id":"706d0ad6-2165-4190-8512-de5abfd06988"}
```

---

### update a group using scim format

`PATCH /gsql/scim/v2/Groups/{id}`

Update a group.

#### Parameters:

None

#### Example:

Sample Request

```bash
curl -X PATCH "Content-type: application/json" "http://localhost:14240/gsql/scim/v2/Groups/g1" -d '
{"schemas":"[\"urn:ietf:params:scim:api:messages:2.0:PatchOp\"]","Operations":[{"op":"remove","path":"members"},{"op":"replace","path":"members","value":[{"display":"user4"}]},{"op":"add","value":[{"display":"user3"}]}]}'
```

Sample Response

```console
{"displayName":"g1","meta":{"location":"/scim/v2/Groups/0b181bc8-d055-4fcb-af52-20c560324c6f","resourceType":"Group"},"members":[{"display":"user3","type":"User","value":"5cdad092-af32-435e-9865-c2ad06b9d6f8"},{"display":"user4","type":"User","value":"c14765de-ea78-422a-bd87-88f3f7d3ceda"}],"id":"0b181bc8-d055-4fcb-af52-20c560324c6f"}
```

---

### drop one group by name using scim format

`DELETE /gsql/scim/v2/Groups/{id}`

Drop one group by name.

#### Parameters:

None

#### Example:

Sample Request

```bash
curl -X DELETE "Content-type: application/json" "http://localhost:14240/gsql/scim/v2/Groups/g1" -d '
{"schemas":"[\"urn:ietf:params:scim:api:messages:2.0:PatchOp\"]","Operations":[{"op":"remove","path":"members"},{"op":"replace","path":"members","value":[{"display":"user4"}]},{"op":"add","value":[{"display":"user3"}]}]}'
```

Sample Response

```console
{"error":false,"message":"Successfully dropped group g1"}
```

---

### drop groups using scim format

`POST /gsql/scim/v2/Groups`

Drop groups.

#### Parameters:

| Name | Required | Description |
| --- | --- | --- |
| `action` | no | The default value is `create`. Possible values are `create` and `delete`. `Delete` indicates dropping groups, while `create` indicates creating groups. |

#### Example:

Sample Request

```bash
curl -X POST "Content-type: application/json" "http://localhost:14240/gsql/scim/v2/Groups?action=delete" -d '{"groupNames":["g1"]}'
```

Sample Response

```console
{"error":false,"message":"Successfully dropped groups: [g1]"}
```

---

### retrieve a user by id using scim format

`GET /gsql/scim/v2/Users/{id}`

Retrieve a user by id respond with scim format.

#### Parameters:

None

#### Example:

Sample Request

```bash
curl -X GET "http://localhost:14240/gsql/scim/v2/Users/u1"
```

Sample Response

```console
{"meta":{"location":"/scim/v2/Users/1e224fd0-54eb-43c3-84d6-455ca3b6339d","resourceType":"User"},"schemas":["urn:ietf:params:scim:schemas:core:2.0:User"],"name":{},"active":true,"id":"1e224fd0-54eb-43c3-84d6-455ca3b6339d","userName":"u1"}
```

---

### update a user using scim format

`PUT /gsql/scim/v2/Users/{id}`

Update a user.

#### Parameters:

None

#### Example:

Sample Request

```bash
curl -X PUT -H "Content-type: application/json" "http://localhost:14240/gsql/scim/v2/Users/u1"  -d '{"schemas":"[\"urn:ietf:params:scim:api:messages:2.0:PatchOp\"]","Operations":[{"op":"replace","path":"password","value":"newPassword"}]}'
```

Sample Response

```console
{"meta":{"location":"/scim/v2/Users/1e224fd0-54eb-43c3-84d6-455ca3b6339d","resourceType":"User"},"schemas":["urn:ietf:params:scim:schemas:core:2.0:User"],"name":{},"active":true,"id":"1e224fd0-54eb-43c3-84d6-455ca3b6339d","userName":"u1"}
```

---

### drop users using scim format

`POST /gsql/scim/v2/Users`

Drop users.

#### Parameters:

| Name | Required | Description |
| --- | --- | --- |
| `action` | no | default: `create`. Possible values: `create`, `delete`. `delete` indicates to drop users; `create` indicates to create users. Here set the value `delete`. |

#### Example:

Sample Request

```bash
curl -X POST -H "Content-type: application/json" "http://localhost:14240/gsql/scim/v2/Users?action=delete"  -d ' {"userNames":["u1"]}'
```

Sample Response

```console
{"error":false,"message":"Successfully dropped users: [u1]"}
```

---

### drop a user using scim format

`DELETE /gsql/scim/v2/Users/{id}`

Drop a user.

#### Parameters:

None

#### Example:

Sample Request

```bash
curl -X DELETE -H "Content-type: application/json" "http://localhost:14240/gsql/scim/v2/Users/u1"
```

Sample Response

```console
{"error":false,"message":"Successfully dropped user u1"}
```

---

### create a user using scim format

`POST /gsql/scim/v2/Users`

Create a user using scim format.

#### Parameters:

None

#### Example:

Sample Request

```bash
curl -X POST -H "Content-type: application/json" "http://localhost:14240/gsql/scim/v2/Users" -d '
{"password":"12345678","schemas":"[\"urn:ietf:params:scim:schemas:core:2.0:User\"]","name":{"familyName":"f","givenName":"g"},"externalId":"externalId123","active":false,"userName":"scimUser2"}'
```

Sample Response

```console
{"meta":{"location":"/scim/v2/Users/d838c224-d1d6-4a07-b6b5-5c0aab43f0a6","resourceType":"User"},"schemas":["urn:ietf:params:scim:schemas:core:2.0:User"],"active":true,"id":"d838c224-d1d6-4a07-b6b5-5c0aab43f0a6","userName":"scimUser2"}
```

---

### retrieve users using scim format

`GET /gsql/scim/v2/Users`

Retrieve users response scim format.

#### Parameters:

| Name | Required | Description |
| --- | --- | --- |
| `excludedAttributes` | no | `names`, currently only support this value. |
| `filter` | no | The format should follow this pattern: `userName op {value} op2 displayName op {value}`. Here, `op` can be one of `eq`, `ne`, `co`, `sw`, `ew`, and `op2` can be either `and` or `or`. Example: 1\. userName eq "user1" 2\. userName sw "u" and userName ne "u1" |

#### Example:

Sample Request

```bash
curl -X GET -H "Content-type: application/json" "http://localhost:14240/gsql/scim/v2/Users?filter=userName%20ne%20%22tigergraph%22%20and%20userName%20sw%20%22u%22&excludedAttributes=names"
```

Sample Response

```console
{"totalResults":2,"startIndex":1,"itemsPerPage":100,"schemas":true,"Resources":[{"meta":{"location":"/scim/v2/Users/7a004538-8d41-4f85-b5e7-2a26358f0173","resourceType":"User"},"schemas":["urn:ietf:params:scim:schemas:core:2.0:User"],"name":{},"active":true,"id":"7a004538-8d41-4f85-b5e7-2a26358f0173","userName":"tigergraph"},{"meta":{"location":"/scim/v2/Users/0a71523d-9623-4b04-908d-395096e288f4","resourceType":"User"},"schemas":["urn:ietf:params:scim:schemas:core:2.0:User"],"name":{},"active":true,"id":"0a71523d-9623-4b04-908d-395096e288f4","userName":"u1"}]}
```

---

## Statistics

### get cardinality statistics

`GET /gsql/v1/stats/cardinality`

Fetch cardinality statistics.

#### Parameters:

| Name | Required | Description |
| --- | --- | --- |
| `graph` | yes | Get the cardinality stats of which graph |

#### Example:

Sample Request

```bash
curl -H 'Content-Type: application/json' -X GET 'http://localhost:14240/gsql/v1/stats/cardinality?graph=financialGraph'
```

Sample Response

```console
{"error":false,"message":"","results":{"vertex_counts":[{"count":5,"type":"Account"}],"edge_counts":[{"count":5,"type":"isLocatedIn"},{"count":10,"from":"Account","to":"City","type":"isLocatedIn"}]}}
```

---

### post cardinality statistics

`POST /gsql/v1/stats/cardinality`

This endpoint has to usage: 1) Fetch fresh up-to-date cardinality statistics and persist it to storage. 2) Persist user defined cardinality statistics to storage.

#### 1) Fetch fresh up-to-date cardinality statistics and persist it to storage

#### Parameters:

| Name | Required | Description |
| --- | --- | --- |
| `graph` | yes | Persist the cardinality stats to which graph |
| `vertex` | no | Fetch fresh up-to-date cardinality stats for specific vertex types and persist them to storage |
| `edge` | no | Fetch fresh up-to-date cardinality stats for specific edge types and persist them to storage, if `vertex` is not empty, this parameter will be ignored |
| `from` | no | Fetch fresh up-to-date cardinality stats for not only specific edge types but also from specific vertex, if `edge` is not empty, this parameter will be ignored, this parameter usually used together with `to`. |
| `to` | no | Fetch fresh up-to-date cardinality stats for not only specific edge types but also to specific vertex, if `edge` is not empty, this parameter will be ignored, this parameter usually used together with `from`. |

##### Example:

Sample Request 1

```bash
curl -H 'Content-Type: application/json' -X POST 'http://localhost:14240/gsql/v1/stats/cardinality?graph=financialGraph&vertex=Account'
```

Sample Response 1

```console
{"error": false,"message": "successfully persisted statistics"}
```

Sample Request 2

```bash
curl -H 'Content-Type: application/json' -X POST 'http://localhost:14240/gsql/v1/stats/cardinality?graph=financialGraph&edge=isLocatedIn&from=Account&to=City'
```

Sample Response 2

```console
{"error": false,"message": "successfully persisted statistics"}
```

#### 2) Persist user defined cardinality statistics to storage.

#### Parameters:

| Name | Required | Description |
| --- | --- | --- |
| `graph` | yes | Persist the cardinality stats to which graph |

##### Example:

Sample Request

```bash
curl -H 'Content-Type: application/json' -X POST 'http://localhost:14240/gsql/v1/stats/cardinality?graph=financialGraph' -d '{"vertex_counts":[{"type": "Account","count": 5}], "edge_counts":[{"type":"hasPhone","count":5},{"type":"isLocatedIn","from":"Account","to":"City","count":10}]}'
```

Sample Response

```console
{"error":false,"message":"","results":{"vertex_counts":[{"count":5,"type":"Account"}],"edge_counts":[{"count":5,"type":"hasPhone"},{"count":10,"from":"Account","to":"City","type":"isLocatedIn"}]}}
```

---

### delete cardinality statistics

`DELETE /gsql/v1/stats/cardinality`

Remove cardinality statistics from storage.

#### Parameters:

| Name | Required | Description |
| --- | --- | --- |
| `graph` | yes | Delete the cardinality stats of indicated graph from storage |

#### Example:

Sample Request

```bash
curl -H 'Content-Type: application/json' -X DELETE 'http://localhost:14240/gsql/v1/stats/cardinality?graph=financialGraph'
```

Sample Response

```console
{"error":false,"message":"successfully deleted statistics"}
```

---

### get histogram statistics

`GET /gsql/v1/stats/histogram`

Fetch histogram statistics.

#### Example:

Sample Request

```bash
curl -H 'Content-Type: application/json' -X GET 'http://localhost:14240/gsql/v1/stats/histogram' -d ' {"graph":"financialGraph", "edge":"isLocatedIn", "from":"Account", "to":"City", "attribute":"name", "bucket":10}'
```

Sample Response

```console
[{"histogram": [{"rowsTotal": 104,"rowsUpper": 1,"upperBound": "2010-05-05 10:44:41"},{"rowsTotal": 12599,"rowsUpper": 1,"upperBound": "2012-06-09 21:24:20"},{"rowsTotal": 15986,"rowsUpper": 1,"upperBound": "2012-09-13 09:27:04"},{"rowsTotal": 1995,"rowsUpper": 1,"upperBound": "2010-11-14 17:07:00"},{"rowsTotal": 3570,"rowsUpper": 1,"upperBound": "2011-02-18 09:33:18"},{"rowsTotal": 4193,"rowsUpper": 1,"upperBound": "2011-05-24 21:54:24"},{"rowsTotal": 5481,"rowsUpper": 1,"upperBound": "2011-08-28 09:45:29"},{"rowsTotal": 752,"rowsUpper": 1,"upperBound": "2010-08-11 07:41:03"},{"rowsTotal": 8665,"rowsUpper": 1,"upperBound": "2012-03-06 08:31:44"},{"rowsTotal": 8880,"rowsUpper": 1,"upperBound": "2011-12-01 21:13:33"}]}]
```

---

### post histogram statistics

`POST /gsql/v1/stats/histogram`

Persist new histogram statistics to storage.

#### Example:

Sample Request

```bash
curl -H 'Content-Type: application/json' -X POST 'http://localhost:14240/gsql/v1/stats/histogram' -d '{"graph":"financialGraph", "edge":"isLocatedIn", "from":"Account", "to":"City", "attribute":"name"}'
```

Sample Response

```console
{"0": {"rowsTotal": 151037,"rowsUpper": 90,"upperBound": 183},"1": {"rowsTotal": 0,"rowsUpper": 0,"upperBound": 399},"2": {"rowsTotal": 0,"rowsUpper": 0,"upperBound": 598},"3": {"rowsTotal": 1,"rowsUpper": 1,"upperBound": 710},"4": {"rowsTotal": 1,"rowsUpper": 1,"upperBound": 908},"5": {"rowsTotal": 1,"rowsUpper": 1,"upperBound": 1119},"6": {"rowsTotal": 1,"rowsUpper": 1,"upperBound": 1211},"7": {"rowsTotal": 1,"rowsUpper": 1,"upperBound": 1402},"8": {"rowsTotal": 0,"rowsUpper": 0,"upperBound": 1789},"9": {"rowsTotal": 1,"rowsUpper": 1,"upperBound": 1988}}
```

---

### delete histogram statistics

`DELETE /gsql/v1/stats/histogram`

Remove histogram statistics from storage.

#### Example:

Sample Request

```bash
curl -H 'Content-Type: application/json' -X DELETE 'http://localhost:14240/gsql/v1/stats/histogram' -d ' {"graph":"financialGraph", "edge":"isLocatedIn", "from":"Account", "to":"City", "attribute":"name"}'
```

Sample Response

```console
{"error": false,"message": "","results": "Deleting any histogram(s) for G.E1.a"}
```

---

## User Defined Objects

### list all tuples

`GET /gsql/v1/udt/tuples`

Get all tuples.

#### Example

Sample Request

```bash
curl -H 'Content-Type: application/json' -X GET 'localhost:14240/gsql/v1/udt/tuples'
```

Sample Response

```console
{"error":false,"message":"","results":[{"name":"TestTup","fields":[{"fieldName":"da","length":8,"fieldType":"UINT"},{"fieldName":"flow","length":8,"fieldType":"STRING"}]}]}
```

---

### list one tuple

`GET /gsql/v1/udt/tuples/{tupleName}`

Get tuple by its name.

#### Parameters:

| Name | Required | Description |
| --- | --- | --- |
| `tupleName` | yes | the tuple name to get information |

#### Example

Sample Request

```bash
curl -H 'Content-Type: application/json' -X GET 'localhost:14240/gsql/v1/udt/tuples/TestTup'
```

Sample Response

```console
{"error":false,"message":"","results":[{"name":"TestTup","fields":[{"fieldName":"da","length":8,"fieldType":"UINT"},{"fieldName":"flow","length":8,"fieldType":"STRING"}]}]}
```

---

### create tuple

`POST /gsql/udt/tuples`

Create a tuple.

#### Example

Sample Request

```bash
curl -H 'Content-Type: application/json' -X POST 'localhost:14240/gsql/v1/udt/tuples?gsql=true' -d '{"gsql":"create tuple commands"}'
or
curl -H 'Content-Type: application/json' -X POST 'localhost:14240/gsql/v1/udt/tuples' -d '{"tuples":[{"Name":"tuple1","TupleElements":[{"name":"attr1","AttributeType":"int"}]}]}'
```

Sample Response

```console
{"error":false,"message":"Successfully create tuples: TestTup."}
```

---

### delete multiple tuples

`DELETE /gsql/v1/udt/tuples`

Delte multiple tuples.

#### Parameters:

| Name | Required | Description |
| --- | --- | --- |
| `tupleName` | yes | the tuple names to be dropped |

#### Example

Sample Request

```bash
curl -H 'Content-Type: application/json' -X DELETE 'localhost:14240/gsql/v1/udt/tuples?tupleName=TestTuple'
```

Sample Response

```console
{"error":false,"message":"Successfully dropped userDefinedTuple: [TestTup]."}
```

---

### delete one tuple

`DELETE /gsql/v1/udt/tuples/{tupleName}`

Delete one tuple by its name.

#### Example

Sample Request

```bash
curl -H 'Content-Type: application/json' -X DELETE 'localhost:14240/gsql/v1/udt/tuples/TestTuple'
```

Sample Response

```console
{"error":false,"message":"Successfully dropped userDefinedTuple: [TestTup]."}
```

---

### list all accumulators

`GET /gsql/v1/udt/accum`

Get all accumulators.

#### Example

Sample Request

```bash
curl -H 'Content-Type: application/json' -X GET 'localhost:14240/gsql/v1/udt/accum'
```

Sample Response

```console
{"error":false,"message":"","results":[{"myGroup":"GroupByAccum<int a, SumAccum<int> b> myGroup\n"}]}
```

---

### list one accumulator

`GET /gsql/v1/udt/accum/{accumName}`

Get one accumulator by its name.

#### Example

Sample Request

```bash
curl -H 'Content-Type: application/json' -X GET 'localhost:14240/gsql/v1/udt/accum/myGroup'
```

Sample Response

```console
{"error":false,"message":"","results":[{"myGroup":"GroupByAccum<int a, SumAccum<int> b> myGroup\n"}]}
```

---

### create accumulators

`POST /gsql/v1/udt/accum`

Create one accumulator.

#### Example

Sample Request

```bash
curl -H 'Content-Type: application/json' -X POST 'localhost:14240/gsql/v1/udt/accum' -d '{"AccumString":"typedef GroupByAccum or typedef HeapAccum"}'
```

Sample Response

```console
{"error":false,"message":"Successfully create accumulator."}
```

---

### delete multiple accumulators

`DELETE /gsql/v1/udt/accum`

Delete multiple accumulators.

#### Parameters:

| Name | Required | Description |
| --- | --- | --- |
| `accumName` | yes | the accumulator names to drop |

#### Example

Sample Request

```bash
curl -H 'Content-Type: application/json' -X DELETE 'localhost:14240/gsql/v1/udt/accum?accumName=myGroup'
```

Sample Response

```console
{"error":false,"message":"Successfully dropped accumulator: [myGroup]."}
```

---

### delete one accumulator

`DELETE /gsql/v1/udt/accum/{accumName}`

Delete one accumulator.

#### Example

Sample Request

```bash
curl -H 'Content-Type: application/json' -X DELETE 'localhost:14240/gsql/v1/udt/accum/myGroup'
```

Sample Response

```console
{"error":false,"message":"Successfully dropped accumulator: [myGroup]."}
```

---

### download user-defined function files

`GET /gsql/v1/udt/files/{fileName}`

Download one of the .hpp files for storing user-defined functions. {fileName} can be one of: \[tg\_\]ExprFunctions, \[tg\_\]ExprUtil, TokenBank.

#### Example

Sample Request

```bash
curl -H 'Content-Type: application/json' -X GET 'localhost:14240/gsql/v1/udt/files/TokenBank'
```

Sample Response

```console
{"error":false,"results": {"TokenBank": "<TokenBank File Content>"}}
```

---

### download all user-defined function files

`GET /gsql/v1/udt/files`

Get all .hpp files used to store user-defined functions: \[tg\_\]ExprFunction.hpp, \[tg\_\]ExprUtil.hpp, TokenBank.hpp.

#### Example

Sample Request

```bash
curl -H 'Content-Type: application/json' -X GET 'localhost:14240/gsql/v1/udt/files'
```

Sample Response

```console
{"error":false,"results": {"TokenBank": "TokenBank File Content", "ExprFunctions": "ExprFunctions file content", "ExprUtil": "", "tg_ExprFunctions": "", "tg_ExprUtil": ""}}
```

---

### upload one user-defined function file

`PUT /gsql/v1/udt/files/{fileName}`

Upload one of the .hpp files for storing user-defined functions. {fileName} can be one of: \[tg\_\]ExprFunctions, \[tg\_\]ExprUtil, TokenBank.

The file contents should be included in payload.

#### Example

Sample Request

```bash
curl -H 'Content-Type: text/plain' -X PUT 'localhost:14240/gsql/v1/udt/files/TokenBank' -d '<Token Bank file content>'
```

Sample Response

```console
{"error":false,"message": "Successfully update file: TokenBank"}
```

---

### upload all user-defined function files

`PUT /gsql/v1/udt/files`

Upload all .hpp files used to store user-defined functions: \[tg\_\]ExprFunction.hpp, \[tg\_\]ExprUtil.hpp, TokenBank.hpp.

See the example for the structure of the data payload.

#### Example

Sample Request

```bash
curl -H 'Content-Type: application/json' -X PUT 'localhost:14240/gsql/v1/udt/files' -d  '{"files":[{"Name":"ExprUtil","Content":"<file content>"}]}'
```

Sample Response

```console
{"error":false,"message": "All files get updated: [TokenBank, ExprFunctions]."}
```

---

### Remove user-defined function files

`DELETE /gsql/v1/udt/files`

Remove one or more of the .hpp files for storing user-defined functions. {fileName} accepts the following 5 filenames: \[tg\_\]ExprFunctions, \[tg\_\]ExprUtil, TokenBank. Use a comma-separated list to remove more than one file.

#### Example

Sample Request

```bash
curl -X DELETE 'localhost:14240/gsql/v1/udt/files?name=ExprFunctions,ExprUtil'
```

Sample Response

```console
{"error":false,"message":"Successfully removed the function files: [ExprFunctions, ExprUtil]."}
```

---

### get token bank functions

`GET /gsql/v1/udt/token-functions/{functionName}`

Get function content by its name.

#### Example

Sample Request

```bash
curl -X GET 'localhost:14240/gsql/v1/udt/token-functions/_Concat'
```

Sample Response

```console
{"error":false,"message":"","results":{"code":"token bank function code","name":"_Concat","returnType":"string"}}
```

---

### get all token bank functions

`GET /gsql/v1/udt/token-functions`

Get all token bank functions.

#### Example

Sample Request

```bash
curl -X GET 'localhost:14240/gsql/v1/udt/token-functions'
```

Sample Response

```console
{"error":false,"message":"","results":[{"code":"token bank function code","name":"_Concat","returnType":"string"}]}
```

---
