diff --git a/antora.yml b/antora.yml index 216b4904..b5dae824 100644 --- a/antora.yml +++ b/antora.yml @@ -1,14 +1,15 @@ name: gsql-ref title: GSQL Language Reference -version: "4.1" -display_version: "4.1" +version: "4.2" +display_version: "4.2" +latest: true start_page: intro:index.adoc nav: -- modules/intro/nav.adoc - modules/tutorials/nav.adoc - modules/basics/nav.adoc - modules/ddl-and-loading/nav.adoc - modules/querying/nav.adoc - modules/openCypher-in-gsql/nav.adoc +- modules/vector/nav.adoc - modules/appendix/nav.adoc diff --git a/modules/API/images/financialGraph_schema.png b/modules/API/images/financialGraph_schema.png deleted file mode 100644 index 0795cd3f..00000000 Binary files a/modules/API/images/financialGraph_schema.png and /dev/null differ diff --git a/modules/API/nav.adoc b/modules/API/nav.adoc deleted file mode 100644 index 9daf2868..00000000 --- a/modules/API/nav.adoc +++ /dev/null @@ -1,2 +0,0 @@ -* xref:index.adoc[REST API Reference] -** xref:gsql-endpoints.adoc[] diff --git a/modules/API/pages/gsql-endpoints.adoc b/modules/API/pages/gsql-endpoints.adoc deleted file mode 100644 index 37dd063e..00000000 --- a/modules/API/pages/gsql-endpoints.adoc +++ /dev/null @@ -1,6420 +0,0 @@ -= GSQL Endpoints -:pp: {plus}{plus} -:description: A set of GSQL REST API endpoints about vertex in TigerGraph server. -:toc: - -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"): - -.Sample schema -image::financialGraph_schema.png - - -== Schema - -=== show vertices - -`GET /gsql/v1/schema/vertices` - -This endpoint is used to show all the local vertices on a graph or show all the global vertices - -==== Parameters: -//[width="100%",cols="25%,25%,50%",options="header",] -[%autowidth] -|=== -| 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 - -[,tabs] -==== -Sample Request:: -+ --- -[source,bash] ----- -curl -X GET -H 'Content-Type: application/json' -u tigergraph:tigergraph "http://localhost:14240/gsql/v1/schema/vertices?graph=financialGraph" ----- --- -Sample Response:: -+ --- -[source.wrap,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}` - -This endpoint is used to show a local/global vertex. - -==== Parameters: -//[width="100%",cols="25%,25%,50%",options="header",] -[%autowidth] -|=== -| 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 - -[,tabs] -==== -Sample Request:: -+ --- -[source,bash] ----- -curl -X GET -H 'Content-Type: application/json' -u tigergraph:tigergraph "http://localhost:14240/gsql/v1/schema/vertices/Account?graph=financialGraph" ----- --- -Sample Response:: -+ --- -[source.wrap,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` - -This endpoint is used to create global vertices using json contains gsql command - -==== Parameters: - -//[width="100%",cols="25%,25%,50%",options="header",] -[%autowidth] -|=== -| 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. -|=== - -==== Example - -[,tabs] -==== -Sample Request:: -+ --- -[source,bash] ----- -curl -X POST -H 'Content-Type: application/json' -u tigergraph:tigergraph "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:: -+ --- -[source.wrap,console] ----- -{"error":false,"message":"Successfully create vertices: [UserA, UserB]"} ----- --- -==== - - -''' - -=== add global vertices to a local graph - -`POST /gsql/v1/schema/vertices` - -This endpoint is used to add existing global vertices to a local graph - -==== Parameters: - -//[width="100%",cols="25%,25%,50%",options="header",] -[%autowidth] -|=== -| Name | Required | Description - -| `graph` -| no -| Specifies the graph to which the global vertices should be added. Here must provide. -|=== - -==== Example - -[,tabs] -==== -Sample Request:: -+ --- -[source,bash] ----- -curl -X POST -H 'Content-Type: application/json' -u tigergraph:tigergraph "http://localhost:14240/gsql/v1/schema/vertices?graph=financialGraph" -d '{"addVertices":["UserA","UserB"]}' ----- --- -Sample Response:: -+ --- -[source.wrap,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 - -[,tabs] -==== -Sample Request:: -+ --- -[source,bash] ----- -curl -X POST -H 'Content-Type: application/json' -u tigergraph:tigergraph "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:: -+ --- -[source.wrap,console] ----- -{"error":false,"message":"Successfully create vertices: [User5, User4]"} ----- --- -==== - -''' - -=== drop vertices - -`DELETE /gsql/v1/schema/vertices` - -This endpoint is used to drop local vertices on specific graph or drop global vertices. - -==== Parameters: - -//[width="100%",cols="25%,25%,50%",options="header",] -[%autowidth] -|=== -| 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 - -[,tabs] -==== -Sample Request:: -+ --- -[source,bash] ----- -curl -X DELETE -H "content-type: text/plain" -u tigergraph:tigergraph "http://localhost:14240/gsql/v1/schema/vertices?vertex=user5,user4" ----- --- -Sample Response:: -+ --- -[source.wrap,console] ----- -{"error":false,"message":"Vertices [user5, user4] deleted successfully."} ----- --- -==== - - -''' - -=== drop a vertex - -`DELETE /gsql/v1/schema/vertices/{vertexName}` - -This endpoint is used to drop a local/global vertex. - -==== Parameters: - -//[width="100%",cols="25%,25%,50%",options="header",] -[%autowidth] -|=== -| 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 - -[,tabs] -==== -Sample Request:: -+ --- -[source,bash] ----- -curl -X DELETE -H "content-type: text/plain" -u tigergraph:tigergraph "http://localhost:14240/gsql/v1/schema/vertices/userB?graph=financialGraph" ----- --- -Sample Response:: -+ --- -[source.wrap,console] ----- -{"error":false,"message":"Vertices [userB] deleted successfully."} ----- --- -==== - - -''' - -=== update a vertex attribute - -`PUT /gsql/v1/schema/vertices/{vertexName}` - -This endpoint is used to update a vertex attributes. - -==== Parameters: -//[width="100%",cols="25%,25%,50%",options="header",] -[%autowidth] -|=== -| 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 - -[,tabs] -==== -Sample Request:: -+ --- -[source,bash] ----- -curl -X PUT -H "content-type: application/json" -u tigergraph:tigergraph "http://localhost:14240/gsql/v1/schema/vertices/Account?graph=financialGraph" -d '{"dropAttributes":["isBlocked"],"addAttributes":[{"AttributeType":{"Name":"STRING"},"AttributeName":"attr1"}]}' ----- --- -Sample Response:: -+ --- -[source.wrap,console] ----- -{"error":false,"message":"Successfully update vertex: Account"} ----- --- -==== - - -''' - -=== show all indexes -`GET /gsql/v1/schema/indexes` - -This endpoint is used to display all indexes within a specific graph or across all global vertices. - -==== Parameters: - -//[width="100%",cols="25%,25%,50%",options="header",] -[%autowidth] -|=== -| 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 -[,tabs] -==== -Sample Request:: -+ --- -[source,bash] ----- -curl -X GET -H "content-type: text/plain" -u tigergraph:tigergraph "http://localhost:14240/gsql/v1/schema/indexes?graph=financialGraph" ----- --- -Sample Response:: -+ --- -[source.wrap,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: - -//[width="100%",cols="25%,25%,50%",options="header",] -[%autowidth] -|=== -| Name | Required | Description - -| `graph` -| no -| Specifies the graph in which the index is located. -|=== - -==== Example -[,tabs] -==== -Sample Request:: -+ --- -[source,bash] ----- -curl -X GET -H "content-type: text/plain" -u tigergraph:tigergraph "http://localhost:14240/gsql/v1/schema/indexes/index_type_name?graph=financialGraph" ----- --- -Sample Response:: -+ --- -[source.wrap,console] ----- -{"error":false,"message":"","results":{"index":"index_type_name","attribute":"name"}} ----- --- -==== - - -''' -=== create indexes -`POST /gsql/v1/schema/indexes` - -This endpoint is used to create indexes. - -==== Parameters: - -//[width="100%",cols="25%,25%,50%",options="header",] -[%autowidth] -|=== -| 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: -[,tabs] -==== -Sample Request:: -+ --- -[source,bash] ----- -curl -X POST -H "content-type: text/plain" -u tigergraph:tigergraph "http://localhost:14240/gsql/v1/schema/indexes?graph=financialGraph" -d '{"vertex":"Account","addIndexAttributes":[{"indexName":"nameIndex","attributeName":"name"}]}' ----- --- -Sample Response:: -+ --- -[source.wrap,console] ----- -{"error":false,"message":"Successfully add index nameIndex on attribute name\n"} ----- --- -==== - - -''' -=== drop an index -`DELETE /gsql/v1/schema/indexes/{indexName}` - -This endpoint is used to drop an index. - -==== Parameters: - -//[width="100%",cols="25%,25%,50%",options="header",] -[%autowidth] -|=== -| 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: -[,tabs] -==== -Sample Request:: -+ --- -[source,bash] ----- -curl -X DELETE -H "content-type: text/plain" -u tigergraph:tigergraph "http://localhost:14240/gsql/v1/schema/indexes/nameIndex" ----- --- -Sample Response:: -+ --- -[source.wrap,console] ----- -{"error":false,"message":"Successfully drop index"} ----- --- -==== - - -''' -=== drop indexes -`DELETE /gsql/v1/schema/indexes` - -This endpoint is used to drop indexes. - -==== Parameters: - -//[width="100%",cols="25%,25%,50%",options="header",] -[%autowidth] -|=== -| 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: -[,tabs] -==== -Sample Request:: -+ --- -[source,bash] ----- -curl -X DELETE -H "content-type: text/plain" -u tigergraph:tigergraph "http://localhost:14240/gsql/v1/schema/indexes?graph=financialGraph&vertex=Account&index=nameIndex" ----- --- -Sample Response:: -+ --- -[source.wrap,console] ----- -{"error":false,"message":"Successfully drop index"} ----- --- -==== - - -''' -=== get all edges - -`GET /gsql/v1/schema/edges` - -This endpoint is used to retrieve all local edges within a specific graph or retrieve all global edges. - -==== Parameters: - -//[width="100%",cols="25%,25%,50%",options="header",] -[%autowidth] -|=== -| Name | Required | Description - -| `graph` -| no -| Specifies the graph from which to retrieve the edges. If not provided, means to get all global edges. -|=== - -==== Example: -[,tabs] -==== -Sample Request:: -+ --- -[source,bash] ----- -curl -X GET -H 'Content-Type: application/json' -u tigergraph:tigergraph "http://localhost:14240/gsql/v1/schema/edges?graph=financialGraph" ----- --- -Sample Response:: -+ --- -[source.wrap,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}` - -This endpoint is used to retrieve information about a specific edge type within a local graph, or retrieve information about a specific global edge type. - -==== Parameters: - -//[width="100%",cols="25%,25%,50%",options="header",] -[%autowidth] -|=== -| 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: -[,tabs] -==== -Sample Request:: -+ --- -[source,bash] ----- -curl -X GET -H 'Content-Type: application/json' -u tigergraph:tigergraph "http://localhost:14240/gsql/v1/schema/edges/isLocatedIn?graph=financialGraph" ----- --- -Sample Response:: -+ --- -[source.wrap,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` - -This endpoint is used to create global edges using gsql command statement. - -==== Parameters: - -//[width="100%",cols="25%,25%,50%",options="header",] -[%autowidth] -|=== -| Name | Required | Description - -| `gsql` -| no -| Indicates whether to use the GSQL command for creating edges. Here must set to true. The request body should contain the GSQL command within the JSON object. -|=== - -==== Example: -[,tabs] -==== -Sample Request:: -+ --- -[source,bash] ----- -curl -X POST -H 'Content-Type: application/json' -u tigergraph:tigergraph "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:: -+ --- -[source.wrap,console] ----- -{"error":false,"message":"Successfully create edges: [edge1, edge2]"} ----- --- -==== - - -''' - -=== add global edges to graph using json format - -`POST /gsql/v1/schema/edges` - -This endpoint is used to add global edges to graph using json format. - -==== Parameters: - -//[width="100%",cols="25%,25%,50%",options="header",] -[%autowidth] -|=== -| Name | Required | Description - -| `graph` -| no -| Specifies the graph to which the global edges will be added. Here must provide. -|=== - -==== Example: -[,tabs] -==== -Sample Request:: -+ --- -[source,bash] ----- -curl -X POST -H "content-type: application/json" -H 'Content-Type: application/json' -u tigergraph:tigergraph "http://localhost:14240/gsql/v1/schema/edges?graph=financialGraph" -d '{"addEdges":["has_account"]}' ----- --- -Sample Response:: -+ --- -[source.wrap,console] ----- -{"error":true,"message":"Failed to create edges [has_account]. Semantic Check Fails: The schema change job tries to add edge has_account to graph financialGraph, but the FROM vertex type user does not exist on the graph.\n"} ----- --- -==== - -''' -=== create global edges using json format - -`POST /gsql/v1/schema/edges` - -This endpoint is used to create global edges using json format. - -==== Parameters: - -None - - -==== Example: -[,tabs] -==== -Sample Request:: -+ --- -[source,bash] ----- -curl -X POST -H 'Content-Type: application/json' -u tigergraph:tigergraph "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:: -+ --- -[source.wrap,console] ----- -{"error":false,"message":"Successfully create edges: [isLocatedIn, hasPhone]"} ----- --- -==== - -''' - -=== drop edges from graph - -`DELETE /gsql/v1/schema/edges` - -This endpoint is used to drop edges from a graph or drop global edges. - -==== Parameters: - -//[width="100%",cols="25%,25%,50%",options="header",] -[%autowidth] -|=== -| 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: -[,tabs] -==== -Sample Request:: -+ --- -[source,bash] ----- -curl -X DELETE -H 'Content-Type: application/json' -u tigergraph:tigergraph "http://localhost:14240/gsql/v1/schema/edges?edge=hasPhone&graph=financialGraph" ----- --- -Sample Response:: -+ --- -[source.wrap,console] ----- -{"error":false,"message":"Edges [hasPhone] deleted successfully."} ----- --- -==== - -''' -=== drop an edge - -`DELETE /gsql/v1/schema/edges/{edgeName}` - -This endpoint is used to drop a local/global edge. - -==== Parameters: - -//[width="100%",cols="25%,25%,50%",options="header",] -[%autowidth] -|=== -| 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: -[,tabs] -==== -Sample Request:: -+ --- -[source,bash] ----- -curl -X DELETE -H "content-type: text/plain" -u tigergraph:tigergraph "http://localhost:14240/gsql/v1/schema/edges/hasPhone?graph=financialGraph" ----- --- -Sample Response:: -+ --- -[source.wrap,console] ----- -{"error":false,"message":"Edges [hasPhone] deleted successfully."} ----- --- -==== - -''' -=== update attribute in edge - -`PUT /gsql/v1/schema/edges/{edgeName}` - -This endpoint is used to update attributes in edge. - -==== Parameters: - -//[width="100%",cols="25%,25%,50%",options="header",] -[%autowidth] -|=== -| 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: -[,tabs] -==== -Sample Request:: -+ --- -[source,bash] ----- -curl -X PUT -H 'Content-Type: application/json' -u tigergraph:tigergraph "http://localhost:14240/gsql/v1/schema/edges/Transfer?graph=financialGraph" -d '{"dropAttributes":["date"],"addAttributes":[{"AttributeType":{"Name":"STRING"},"AttributeName":"attr"}]}' ----- --- -Sample Response:: -+ --- -[source.wrap,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` - -This endpoint is used to show all graphs info only containing names of vertices and edges. - -==== Parameters: - -None - -==== Example: -[,tabs] -==== -Sample Request:: -+ --- -[source,bash] ----- -curl -X GET -H 'Content-Type: application/json' -u tigergraph:tigergraph "http://localhost:14240/gsql/v1/schema/graphs" ----- --- -Sample Response:: -+ --- -[source.wrap,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}` - -This endpoint is used to show one graph detailed info with given graph name. - -==== Parameters: - -None - -==== Example: -[,tabs] -==== -Sample Request:: -+ --- -[source,bash] ----- -curl -X GET -H "content-type: application/json" -u tigergraph:tigergraph "http://localhost:14240/gsql/v1/schema/graphs/financialGraph" ----- --- -Sample Response:: -+ --- -[source.wrap,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` - -This endpoint is used to create one graph using gsql command. - -==== Parameters: - -//[width="100%",cols="25%,25%,50%",options="header",] -[%autowidth] -|=== -| 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: -[,tabs] -==== -Sample Request:: -+ --- -[source,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:: -+ --- -[source.wrap,console] ----- -{"error":false,"message":"Successfully created graph: [g]."} ----- --- -==== - -''' - -=== create one graph using JSON format - -`POST /gsql/v1/schema/graphs` - -This endpoint is used to create one graph using JSON format. - -==== Parameters: - -//[width="100%",cols="25%,25%,50%",options="header",] -[%autowidth] -|=== -| 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: -[,tabs] -==== -Sample Request:: -+ --- -[source,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:: -+ --- -[source.wrap,console] ----- -{"error":false,"message":"Successfully created graph: [gtest]."} ----- --- -==== - -''' - -=== drop one graph - -`DELETE /gsql/v1/schema/graphs/{graphName}` - -This endpoint is used to drop one graph. - -==== Parameters: - -//[width="100%",cols="25%,25%,50%",options="header",] -[%autowidth] -|=== -| 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: -[,tabs] -==== -Sample Request:: -+ --- -[source,bash] ----- -curl -X DELETE -H "content-type: text/plain" "http://localhost:14240/gsql/v1/schema/graphs/financialGraph?cascade=true" ----- --- -Sample Response:: -+ --- -[source.wrap,console] ----- -{"error":false,"message":"Successfully dropped graph: financialGraph."} ----- --- -==== - -''' - -=== drop graphs with given names - -`DELETE /gsql/v1/schema/graphs` - -This endpoint is used to drop graphs with given names. - -==== Parameters: - -//[width="100%",cols="25%,25%,50%",options="header",] -[%autowidth] -|=== -| Name | Required | Description - -| `graphNames` -| yes -| Specifies the names of the graphs to be dropped, separated by commas. Use 'all' to drop all graphs. -|=== - -==== Example: -[,tabs] -==== -Sample Request:: -+ --- -[source,bash] ----- -curl -X DELETE -H "content-type: text/plain" "http://localhost:14240/gsql/v1/schema/graphs?graphNames=financialGraph,recommend" ----- --- -Sample Response:: -+ --- -[source.wrap,console] ----- -{"error":false,"message":"Successfully dropped graphs: [financialGraph, recommend]."} ----- --- -==== - -''' -=== drop local/global schema change jobs - -`DELETE /gsql/v1/schema/jobs` - -This endpoint is used to drop local/global schema change jobs. - -==== Parameters: - -//[width="100%",cols="25%,25%,50%",options="header",] -[%autowidth] -|=== -| 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: -[,tabs] -==== -Sample Request:: -+ --- -[source,bash] ----- -curl -X DELETE -H "content-type: text/plain" "http://localhost:14240/gsql/v1/schema/jobs?jobName=test1,test2&graph=financialGraph" ----- --- -Sample Response:: -+ --- -[source.wrap,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}` - -This endpoint is used to create local/global schema change job using gsql command. - -==== Parameters: - -//[width="100%",cols="25%,25%,50%",options="header",] -[%autowidth] -|=== -| 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: -[,tabs] -==== -Sample Request:: -+ --- -[source,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:: -+ --- -[source.wrap,console] ----- -{"error":false,"message":"Successfully created global schema change job: [test3]."} ----- --- -==== - - -''' -=== create global schema change job using json - -`POST /gsql/v1/schema/jobs/{jobName}` - -This endpoint is used to create global schema change job using json. - -==== Parameters: - -None - -==== Example: -[,tabs] -==== -Sample Request:: -+ --- -[source,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:: -+ --- -[source.wrap,console] ----- -{"error":false,"message":"Successfully created global schema change job: [test4]."} ----- --- -==== - - -''' -=== create local schema change job using json - -`POST /gsql/v1/schema/jobs/{jobName}` - -This endpoint is used to create local schema change job using json. - -==== Parameters: - -//[width="100%",cols="25%,25%,50%",options="header",] -[%autowidth] -|=== -| 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: - -[source] ----- -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 -) ----- - -[,tabs] -==== -Sample Request:: -+ --- -[source,bash] ----- -curl -X POST -H "content-type: application/json" -u tigergraph:tigergraph "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:: -+ --- -[source.wrap,console] ----- -{"error":false,"message":"Successfully created schema change job: [test5]."} ----- --- -==== - -''' -=== get a specific local/global schema change job - -`GET /gsql/v1/schema/jobs/{jobName}` - -This endpoint is used to retrieve a specific local/global schema change job. - -==== Parameters: - -//[width="100%",cols="25%,25%,50%",options="header",] -[%autowidth] -|=== -| 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: -[,tabs] -==== -Sample Request:: -+ --- -[source,bash] ----- -curl -X GET -H "content-type: application/json" "http://localhost:14240/gsql/v1/schema/jobs/job12?json=true&graph=financialGraph" ----- --- -Sample Response:: -+ --- -[source.wrap,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` - -This endpoint is used to run global schema change job directly. - -==== Parameters: - -None - -==== Example: -[,tabs] -==== -Sample Request:: -+ --- -[source,bash] ----- -curl -X POST -H "content-type: application/json" -u tigergraph:tigergraph "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:: -+ --- -[source.wrap,console] ----- -{"error":false,"message":"Global schema change runs successfully"} ----- --- -==== - -''' -=== run the schema change job directly - -`POST /gsql/v1/schema/change` - -This endpoint is used to run the schema change job directly. - -==== Parameters: - -//[width="100%",cols="25%,25%,50%",options="header",] -[%autowidth] -|=== -| 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. -|=== - -==== Example: -[,tabs] -==== -Sample Request:: -+ --- -[source,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:: -+ --- -[source.wrap,console] ----- -{"error":false,"message":"Schema change job runs successfully"} ----- --- -==== - -''' -=== run an existing schema change job - -`POST /gsql/v1/schema/jobs/{jobName}` - -This endpoint is used to run an existing schema change job. - -==== Parameters: - -//[width="100%",cols="25%,25%,50%",options="header",] -[%autowidth] -|=== -| Name | Required | Description - -| `graph` -| no -| which graph to run the schema change job on. If not provided, means run the global schema change job. -|=== - -==== Example: -[,tabs] -==== -Sample Request:: -+ --- -[source,bash] ----- -curl -X POST -H "content-type: application/json" "http://localhost:14240/gsql/v1/schema/jobs/test5?graph=financialGraph" ----- --- -Sample Response:: -+ --- -[source.wrap,console] ----- -{"error":false,"message":"Schema change job run successfully!"} ----- --- -==== - -''' -=== get schema change jobs - -`GET /gsql/v1/schema/jobs` - -This endpoint is used to get all local/global schema change jobs. - -==== Parameters: - -//[width="100%",cols="25%,25%,50%",options="header",] -[%autowidth] -|=== -| 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: -[,tabs] -==== -Sample Request:: -+ --- -[source,bash] ----- -curl -X GET -H "content-type: application/json" -u tigergraph:tigergraph "http://localhost:14240/gsql/v1/schema/jobs?graph=financialGraph" ----- --- -Sample Response:: -+ --- -[source.wrap,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 job - -=== get loading job names - -`GET /gsql/v1/loading-jobs` - -This endpoint is used to get all loading job names in a graph. - -==== Parameters: - -//[width="100%",cols="25%,25%,50%",options="header",] -[%autowidth] -|=== -| Name | Required | Description - -| `graph` -| yes -| the loading job names of which graph -|=== - -==== Example - -[,tabs] -==== -Sample Request:: -+ --- -[source,bash] ----- -curl -H 'Content-Type: application/json' -X GET 'http://localhost:14240/gsql/v1/loading-jobs?graph=financialGraph' ----- --- -Sample Response:: -+ --- -[source.wrap,console] ----- -{"error":false,"message":"","jobNames":["incidents_fraud_report_company_csv"]} ----- --- -==== - -''' - -=== create a loading job - -`POST /gsql/v1/loading-jobs` - -This endpoint is used to create a new loading job - -==== Parameters: - -//[width="100%",cols="25%,25%,50%",options="header",] -[%autowidth] -|=== -| Name | Required | Description - -| `graph` -| yes -| create loading job of which graph -|=== - -==== Example - -[,tabs] -==== -Sample Request:: -+ --- -[source,bash] ----- -curl -H 'Content-Type: text/plain' -X POST 'http://localhost:14240/gsql/v1/loading-jobs?graph=financialGraph' -d '' ----- --- -Sample Response:: -+ --- -[source.wrap,console] ----- -{"error":false,"message":"Successfully created loading job: "} ----- --- -==== - -''' - -=== upload a loading job - -`PUT /gsql/v1/loading-jobs` - -This endpoint is used to update an existing loading job. - -==== Parameters: - -//[width="100%",cols="25%,25%,50%",options="header",] -[%autowidth] -|=== -| Name | Required | Description - -| `graph` -| yes -| update loading job of which graph -|=== - -==== Example - -[,tabs] -==== -Sample Request:: -+ --- -[source,bash] ----- -curl -H 'Content-Type: text/plain' -X PUT 'http://localhost:14240/gsql/v1/loading-jobs?graph=financialGraph' -d '' ----- --- -Sample Response:: -+ --- -[source.wrap,console] ----- -{"error":false,"message":"Successfully created loading job: "} ----- --- -==== - -''' - -=== get loading job info - -`GET /gsql/v1/loading-jobs/{jobName}` - -This endpoint is used to get a specific loading job's information. - -==== Parameters: - -//[width="100%",cols="25%,25%,50%",options="header",] -[%autowidth] -|=== -| Name | Required | Description - -| `graph` -| yes -| get the loading job information under which graph - -| `verbose` -| no -| default: false, true means show verbose version, true means show concise version. -|=== - -==== Example - -[,tabs] -==== -Sample Request:: -+ --- -[source,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:: -+ --- -[source.wrap,console] ----- -Default behavior: -json=false: -{"error":false,"message":"","results":{"jobName":"incidents_fraud_report_company_csv","jobContent":"this is jobContent"}} - -json=true: {"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"}}]}} ----- --- -==== - -''' - -=== run loading job - -`POST /gsql/v1/loading-jobs/run` - -This endpoint is used to run a loading job. - -==== Parameters: - -//[width="100%",cols="25%,25%,50%",options="header",] -[%autowidth] -|=== -| Name | Required | Description - -| `graph` -| yes -| run the loading job under which graph -|=== - -==== Example - -[,tabs] -==== -Sample Request:: -+ --- -[source,bash] ----- -curl -H 'Content-Type: application/json' -X POST 'http://localhost:14240/gsql/v1/loading-jobs/run?graph=financialGraph' -payload could be one of these: -kafka loading: [{"name":"load_kafka","dataSources":[{"filename":"f1","name":"k1","path":"","config":{"topic":"regress7715","partition_list":[{"start_offset":-2,"partition":0}]}}],"streaming":false}] -s3: [{"name":"load_comment","streaming":true,"dataSources":[{"filename":"file_Comment","name":"s1","path":"s3-loading-test/tg_ldbc_snb/sf0.1_csv/dynamic/Comment"}]}] -file loading: [{"name":"load_job","sys.data_root":"/tmp","dataSources":[{"filename":"f","path":"./data","name":"file"}]}] -full parameters: [{"name":"load_job","sys.data_root":"/tmp","verbose":true,"dryrun":true,"interval":1,"maxNumError":1,"maxPercentError":1,"dataSources":[{"filename":"f","path":"./data","name":"file"}]}] ----- --- -Sample Response:: -+ --- -[source.wrap,console] ----- -{"error": false,"message":"Successfully ran loading job(s): [jobName]", "jobIds": ["jobId"]} ----- --- -==== - -''' - -=== drop a loading job - -`DELETE /gsql/v1/loading-jobs/{jobName}` - -This endpoint is used to drop a loading job by name. - -==== Parameters: - -//[width="100%",cols="25%,25%,50%",options="header",] -[%autowidth] -|=== -| Name | Required | Description - -| `graph` -| yes -| drop the loading job under which graph -|=== - -==== Example - -[,tabs] -==== -Sample Request:: -+ --- -[source,bash] ----- -curl -H 'Content-Type: application/json' -X DELETE 'http://localhost:14240/gsql/v1/loading-jobs/jobName?graph=financialGraph' ----- --- -Sample Response:: -+ --- -[source.wrap,console] ----- -{"error": false,"message":"Successfully drop loading job 'jobName'."} ----- --- -==== - -''' - -=== abort loading job(s) - -`GET /gsql/v1/loading-jobs/abort` - -This endpoint is used to abort mutilple running loading jobs. - -==== Parameters: - -//[width="100%",cols="25%,25%,50%",options="header",] -[%autowidth] -|=== -| Name | Required | Description - -| `graph` -| yes -| abort the loading job under which graph - -| `jobIds` -| yes -| the loading job Ids -|=== - -==== Example - -[,tabs] -==== -Sample Request:: -+ --- -[source,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=jobId1&isPause=true' ----- --- -Sample Response:: -+ --- -[source.wrap,console] ----- -default behavior: {"error": false,"message":"Successfully dropped loading job(s): [jobId1]."} -{"error": false,"message":"Successfully paused loading job(s): [jobId1]."} ----- --- -==== - -''' - -=== abort one loading job - -`GET /gsql/v1/loading-jobs/abort/{jobId}` - -This endpoint is used to abort a one loading job by job Id. - -==== Parameters: - -//[width="100%",cols="25%,25%,50%",options="header",] -[%autowidth] -|=== -| Name | Required | Description - -| `graph` -| yes -| abort the loading job under which graph - -| `jobId` -| yes -| the loading job Id -|=== - - -==== Example - -[,tabs] -==== -Sample Request:: -+ --- -[source,bash] ----- -curl -H 'Content-Type: application/json' -X GET 'http://localhost:14240/gsql/v1/loading-jobs/jobId1?graph=financialGraph' ----- --- -Sample Response:: -+ --- -[source.wrap,console] ----- -default behavior: {"error": false,"message":"Successfully dropped loading job(s): [jobId1]."} -{"error": false,"message":"Successfully paused loading job(s): [jobId1]."} ----- --- -==== - -''' - -=== resume loading job - -`GET /gsql/v1/loading-jobs/resume/{jobId}` - -This endpoint is used to resume a paused loading job by job Id. - -==== Parameters: - -//[width="100%",cols="25%,25%,50%",options="header",] -[%autowidth] -|=== -| Name | Required | Description - -| `jobId` -| yes -| the loading job Id -|=== - -==== Example - -[,tabs] -==== -Sample Request:: -+ --- -[source,bash] ----- -curl -H 'Content-Type: application/json' -X GET 'http://localhost:14240/gsql/v1/loading-jobs/resume/jobId1' ----- --- -Sample Response:: -+ --- -[source.wrap,console] ----- -{"error": false,"message":"Successfully resumed loading job(s): [jobId1]."} ----- --- -==== - -''' - -=== get loading job status - -`GET /gsql/v1/loading-jobs/status` - -This endpoint is used to get multiple loading jobs status. - -==== Parameters: - -//[width="100%",cols="25%,25%,50%",options="header",] -[%autowidth] -|=== -| Name | Required | Description - -| `jobIds` -| yes -| the loading job Ids -|=== - -==== Example - -[,tabs] -==== -Sample Request:: -+ --- -[source,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:: -+ --- -[source.wrap,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 one loading job status - -`GET /gsql/v1/loading-jobs/status/{jobId}` - -This endpoint is used to get a loading job's status by job Id. - -==== Parameters: - -//[width="100%",cols="25%,25%,50%",options="header",] -[%autowidth] -|=== -| Name | Required | Description - -| `jobId` -| yes -| the loading job Id -|=== - -==== Example - -[,tabs] -==== -Sample Request:: -+ --- -[source,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:: -+ --- -[source.wrap,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"}]}]}]} ----- --- -==== - -''' - - -== Data source - -=== get a data source - -`GET /gsql/v1/data-sources/{dsName}` - -This endpoint is used to get a data source. - -==== Parameters: - -None - -==== Example: -[,tabs] -==== -Sample Request:: -+ --- -[source,bash] ----- -curl -X GET "http://localhost:14240/gsql/v1/data-sources/k1" ----- --- -Sample Response:: -+ --- -[source.wrap,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` - -This endpoint is used to get all data sources. - -==== Parameters: - -None - -==== Example: -[,tabs] -==== -Sample Request:: -+ --- -[source,bash] ----- -curl -X GET "http://localhost:14240/gsql/v1/data-sources" ----- --- -Sample Response:: -+ --- -[source.wrap,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` - -This endpoint is used to update a data source . - -==== Parameters: - -//[width="100%",cols="25%,25%,50%",options="header",] -[%autowidth] -|=== -| Name | Required | Description - -| `graph` -| no -| the graph whose data source to update. If not provided, means to update a global data source. -|=== - -==== Example: -[,tabs] -==== -Sample Request:: -+ --- -[source,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:: -+ --- -[source.wrap,console] ----- -{"error":false,"message":"Data source s5 is created"} ----- --- -==== - -''' -=== create data source - -`POST /gsql/v1/data-sources` - -This endpoint is used to create a data source. - -==== Parameters: - -//[width="100%",cols="25%,25%,50%",options="header",] -[%autowidth] -|=== -| Name | Required | Description - -| `graph` -| no -| the graph whose data source to create. If not provided, means to create a global data source. -|=== - -==== Example: -[,tabs] -==== -Sample Request:: -+ --- -[source,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:: -+ --- -[source.wrap,console] ----- -{"error":false,"message":"Data source s4 is created"} ----- --- -==== - -''' -=== drop one data source - -`DELETE /gsql/v1/data-sources/{dsName}` - -This endpoint is used to drop one data source. - -==== Parameters: - -//[width="100%",cols="25%,25%,50%",options="header",] -[%autowidth] -|=== -| Name | Required | Description - -| `graph` -| no -| the graph whose data source to delete. If not provided, means to delete a global data source. -|=== - -==== Example: -[,tabs] -==== -Sample Request:: -+ --- -[source,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:: -+ --- -[source.wrap,console] ----- -{"error":false,"message":"Data source k1 is dropped."} ----- --- -==== - -''' -=== grant one data source - -`POST /gsql/v1/data-sources/grant` - -This endpoint is used to grant one data source. - -==== Parameters: - -None - -==== Example: -[,tabs] -==== -Sample Request:: -+ --- -[source,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:: -+ --- -[source.wrap,console] ----- -{"error":false,"message":"Successfully grant datasource k1 to the graph(s) [empty_graph, person_movie]"} ----- --- -==== - -''' -=== revoke datasource - -`POST /gsql/v1/data-sources/revoke` - -This endpoint is used to revoke data source. - -==== Parameters: - -None - -==== Example: -[,tabs] -==== -Sample Request:: -+ --- -[source,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:: -+ --- -[source.wrap,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` - -This endpoint is used to drop all data source. - -==== Parameters: - -//[width="100%",cols="25%,25%,50%",options="header",] -[%autowidth] -|=== -| 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: -[,tabs] -==== -Sample Request:: -+ --- -[source,bash] ----- -curl -X DELETE 'Content-type: text/plain' "http://localhost:14240/gsql/v1/data-sources/dropAll" ----- --- -Sample Response:: -+ --- -[source.wrap,console] ----- -{"error":false,"message":"All data sources is dropped successfully."} ----- --- -==== - -''' -=== get the sample data of S3 file.uris or local files - -`POST /gsql/v1/sample-data` - -This endpoint is used to get the sample data of S3 file.uris or local files. - -==== Parameters: - -None - -==== Example: -[,tabs] -==== -Sample Request:: -+ --- -[source,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:: -+ --- -[source.wrap,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}` - -This endpoint is used to get all buckets of given S3 data source. - -==== Parameters: - -None - -==== Example: -[,tabs] -==== -Sample Request:: -+ --- -[source,bash] ----- -curl -X GET 'Content-type: text/plain' "http://localhost:14240/gsql/v1/list-buckets/abcd" ----- --- -Sample Response:: -+ --- -[source.wrap,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","cloud-gbar-test","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","gbar-test","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-gbar","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}` - -This endpoint is used to get all files and directories under given S3 bucket path. - -==== Parameters: - -//[width="100%",cols="25%,25%,50%",options="header",] -[%autowidth] -|=== -| Name | Required | Description - -| `path` -| no -| Uri of the data source. If not provide, list files under `/` -|=== - -==== Example: -[,tabs] -==== -Sample Request:: -+ --- -[source,bash] ----- -curl -X GET 'Content-type: text/plain' "http://localhost:14240/gsql/v1/list-files/fl2323?path=s3a://import-test" ----- --- -Sample Response:: -+ --- -[source.wrap,console] ----- -{"error":false,"results":{"folders":["test-folder"],"files":["chinese.csv","movies.csv","ratings.csv","ratings.tar","ratings.tar.gz","ratings.zip","中文®初めまして.csv"]}} ----- --- -==== - -''' - -== Query - -=== install queries - -`GET /gsql/v1/queries/install` - -This api is used for installing queries - -==== Parameters: - -//[width="100%",cols="25%,25%,50%",options="header",] -[%autowidth] -|=== -| 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: -[,tabs] -==== -Sample Request:: -+ --- -[source,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:: -+ --- -[source.wrap,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: -[,tabs] -==== -Sample Request:: -+ --- -[source,bash] ----- -curl -X GET -H "Content-type: text/plain" "http://localhost:14240/gsql/v1/queries/install/121212121331" ----- --- -Sample Response:: -+ --- -[source.wrap,console] ----- -{ -"error":false, -"message":"Request 121212121331 is running", -"requestId" : "121212121331", -"startTime": "2024-07-07T23:17:06.831474Z" -} ----- --- -==== - -''' - -=== list query names - -`GET /gsql/v1/queries` - -This endpoint is used to get all query names of a graph. - -==== Example - -[,tabs] -==== -Sample Request:: -+ --- -[source,bash] ----- -curl -H 'Content-Type: application/json' -X GET 'http://localhost:14240/gsql/v1/quries?graph=financialGraph' ----- --- -Sample Response:: -+ --- -[source.wrap,console] ----- -{"error":false,"message":"","results":["query1","query2"]} ----- --- -==== - -''' - -=== create query - -`POST /gsql/v1/queries` - -This endpoint is used to create a query. - -==== Parameters: - -//[width="100%",cols="25%,25%,50%",options="header",] -[%autowidth] -|=== -| Name | Required | Description - -| `graph` -| yes -| the query created under which graph -|=== - -==== Example - -[,tabs] -==== -Sample Request:: -+ --- -[source,bash] ----- -curl -H 'Content-Type: text/plain' -X POST 'http://localhost:14240/gsql/v1/quries?graph=financialGraph' -d 'create query q1 {...}' ----- --- -Sample Response:: -+ --- -[source.wrap,console] ----- -{"error":false,"message":"Successfully created queries: [q1].\n"} ----- --- -==== - -''' - -=== drop query - -`DELETE /gsql/v1/queries` - -This endpoint is used to drop quries. - -==== Parameters: - -//[width="100%",cols="25%,25%,50%",options="header",] -[%autowidth] -|=== -| Name | Required | Description - -| `query` -| yes -| the queries to be dropped - -| `graph` -| yes -| the queries dropped under which graph -|=== - -==== Example - -[,tabs] -==== -Sample Request:: -+ --- -[source,bash] ----- -curl -H 'Content-Type: application/json' -X DELETE 'http://localhost:14240/gsql/v1/queries?query=q1&graph=financialGraph' ----- --- -Sample Response:: -+ --- -[source.wrap,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: - -//[width="100%",cols="25%,25%,50%",options="header",] -[%autowidth] -|=== -| Name | Required | Description - -| `queryName` -| yes -| the content of which query - -| `graph` -| yes -| the query under which graph -|=== - -==== Example - -[,tabs] -==== -Sample Request:: -+ --- -[source,bash] ----- -curl -H 'Content-Type: application/json' -X GET 'http://localhost:14240/gsql/v1/queires/q1?graph=financialGraph ----- --- -Sample Response:: -+ --- -[source.wrap,console] ----- -{"queryContent":"CREATE QUERY q1() { print 1;}","name":"test","syntax":"GSQL v2","error":false,"message":"","status":"VALID"} ----- --- -==== - -''' - -=== run query - -`POST /gsql/v1/queires/{queryName}` - -The endpoint is used to run a query by its name. - -==== Parameters: - -//[width="100%",cols="25%,25%,50%",options="header",] -[%autowidth] -|=== -| Name | Required | Description - -| `queryName` -| yes -| the query to run -|=== - -==== Example - -[,tabs] -==== - -Sample Query:: -+ --- -[source,bash] ----- -CREATE QUERY q1(String param1) { print param1;} ----- --- -Sample Request:: -+ --- -[source,bash] ----- -curl -H 'Content-Type: application/json' -X POST 'http://localhost:14240/gsql/v1/queires/q1?graph=financialGraph --d '{"diagnose":false,"denseMode":false,"allvertex":false,"asyncRun":false,"parameters":{"param1":"1"}}' ----- --- -Sample Response:: -+ --- -[source.wrap,console] ----- -{"error":false,"message":"","results":{"error":false,"message":"","version":{"schema":1,"edition":"enterprise","api":"v2"},"results":[{"1":1}]}} ----- --- -==== - -''' - -=== drop one query - -`DELETE /gsql/v1/queries/{queryName}` - -This endpoint is used to drop a query by its name. - -==== Parameters: - -//[width="100%",cols="25%,25%,50%",options="header",] -[%autowidth] -|=== -| Name | Required | Description - -| `queryName` -| yes -| the query to drop -|=== - -==== Example - -[,tabs] -==== -Sample Request:: -+ --- -[source,bash] ----- -curl -H 'Content-Type: application/json' -X DELETE 'http://localhost:14240/gsql/v1/queires/q1?graph=financialGraph ----- --- -Sample Response:: -+ --- -[source.wrap,console] ----- -{"failedToDrop":[],"dropped":["q1"],"error":false,"message":""} ----- --- -==== - -''' - -=== interpret query - -`POST /gsql/v1/queries/interpret` - -This endpoint is used to intepret query. Please note that calling this endpont need to set 'Content-Type: text/plain' in header. - -==== Parameters: - -//[width="100%",cols="25%,25%,50%",options="header",] -[%autowidth] -|=== -| Name | Required | Description - -| `graph` -| yes -| the query interpreted under which graph -|=== - -==== Example - -[,tabs] -==== -Sample Request:: -+ --- -[source,bash] ----- -curl -H 'Content-Type: text/plain' -X POST 'localhost:14240/gsql/v1/queries/interpret?p1=hello&p1=world' -d 'INTERPRET QUERY (SET p1) FOR GRAPH financialGraph syntax v1 { print p1; }' ----- --- -Sample Response:: -+ --- -[source.wrap,console] ----- -{"error":false,"message":"","version":{"schema":1,"edition":"enterprise","api":"v2"},"results":[{"p1":["hello","world"]}]} ----- --- -==== - -''' - -=== get query info - -`GET /gsql/v1/queries/info` - -This endpoint is used to get the query's information. - -==== Parameters: - -//[width="100%",cols="25%,25%,50%",options="header",] -[%autowidth] -|=== -| Name | Required | Description - -| `graph` -| yes -| the query under which graph - -| `query` -| no -| the query name - -| `status` -| no -| the query status -|=== - -==== Example - -[,tabs] -==== -Sample Request:: -+ --- -[source,bash] ----- -curl -H 'Content-Type: application/json' -X GET 'localhost:14240/gsql/v1/queries/info?graph=financialGraph' ----- --- -Sample Response:: -+ --- -[source.wrap,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` - -This endpoint is used to get query's signature by its name. - -==== Parameters: - -//[width="100%",cols="25%,25%,50%",options="header",] -[%autowidth] -|=== -| 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 - -[,tabs] -==== -Sample Request:: -+ --- -[source,bash] ----- -curl -H 'Content-Type: text/plain' -X GET 'localhost:14240/gsql/v1/queries/signature?queryName=q1&graph=financialGraph' ----- --- -Sample Response:: -+ --- -[source.wrap,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` - -This endpoint is used to query semantic check. - -==== Example - -[,tabs] -==== -Sample Request:: -+ --- -[source,bash] ----- -curl -H 'Content-Type: application/json' -X POST 'localhost:14240/gsql/v1/internal/check/query' -d ' {"code":""}' ----- --- -Sample Response:: -+ --- -[source.wrap,console] ----- -{"warnings":[],"errors":[]} ----- --- -==== - -''' - -== templeta query - -=== get all package names - -`GET /gsql/v1/packages` - -This endpoint is used to get all package names. - -==== Example - -[,tabs] -==== -Sample Request:: -+ --- -[source,bash] ----- -curl -H 'Content-Type: application/json' -X GET 'localhost:14240/gsql/v1/packages ----- --- -Sample Response:: -+ --- -[source.wrap,console] ----- -{"error":false,"message":"","results":["gds","gds.community"]} ----- --- -==== - -''' - -=== get package content - -`GET /gsql/v1/package/{packageName}` - -This endpoint is used to get package by its name. - -==== Example - -[,tabs] -==== -Sample Request:: -+ --- -[source,bash] ----- -curl -H 'Content-Type: application/json' -X GET 'localhost:14240/gsql/v1/packages/gds.community ----- --- -Sample Response:: -+ --- -[source.wrap,console] ----- -{"error":false,"message":"","results":{"fullPackageName":"gds.community","functions":[],"templateQueries":["printVertex"],"subpackageNames":[]}} ----- --- -==== - -''' - -=== create package - -`POST /gsql/v1/package/{packageName}` - -This endpoint is used to create package. - -==== Example - -[,tabs] -==== -Sample Request:: -+ --- -[source,bash] ----- -curl -H 'Content-Type: text/plain' -X POST 'localhost:14240/gsql/v1/packages/gds.commumity1 ----- --- -Sample Response:: -+ --- -[source.wrap,console] ----- -{"error":false,"message":"Successfully created package: [gds.community1]."} ----- --- -==== - -''' - -=== drop package - -`DELETE /gsql/v1/package/{packageName}` - -This endpoint is used to drop package by its name. - -==== Example - -[,tabs] -==== -Sample Request:: -+ --- -[source,bash] ----- -curl -X DELETE 'localhost:14240/gsql/v1/packages/gds.commumity1 ----- --- -Sample Response:: -+ --- -[source.wrap,console] ----- -{"error":false,"message":"Successfully dropped package: [gds.community1]."} ----- --- -==== - -''' - -=== create function - -`POST /gsql/v1/package/function` - -This endpoint is used to create function - -==== Example - -[,tabs] -==== -Sample Request:: -+ --- -[source,bash] ----- -curl -H 'Content-Type: text/plain' -X POST 'localhost:14240/gsql/v1/packages/function -d 'create function gds.community.func1 {}' ----- --- -Sample Response:: -+ --- -[source.wrap,console] ----- -{"error":false,"message":"Successfully created function: [gds.community.func1]."} ----- --- -==== - -''' - -=== delete function - -`DELETE /gsql/v1/package/{functionName}` - -This endpoint is used to delete function by its name. - -==== Example - -[,tabs] -==== -Sample Request:: -+ --- -[source,bash] ----- -curl -X DELETE 'localhost:14240/gsql/v1/packages/function/gds.community.func1' ----- --- -Sample Response:: -+ --- -[source.wrap,console] ----- -{"error":false,"message":"Successfully dropped function: [gds.community.func1]."} ----- --- -==== - -''' - -=== create template query - -`POST /gsql/v1/package/template` - -This endpoint is used to create template query. - -==== Example - -[,tabs] -==== -Sample Request:: -+ --- -[source,bash] ----- -curl -H 'Content-Type: text/plain' -X POST 'localhost:14240/gsql/v1/packages/template' -d 'create template query gds.community.templateQuery1 {}' ----- --- -Sample Response:: -+ --- -[source.wrap,console] ----- -{"error":false,"message":"Successfully created template query: [gds.community.templateQuery1]."} ----- --- -==== - -''' - -=== drop template query - -`DELETE /gsql/v1/package/template/{queryName}` - -This endpoint is used to drop template query. - -==== Example - -[,tabs] -==== -Sample Request:: -+ --- -[source,bash] ----- -curl -X DELETE 'localhost:14240/gsql/v1/packages/template/gds.community.templateQuery1' ----- --- -Sample Response:: -+ --- -[source.wrap,console] ----- -{"error":false,"message":"Successfully dropped template query: [gds.community.templateQuery1]."} ----- --- -==== - -''' - -=== import package - -`POST /gsql/v1/package/import/{packageName}` - -This endpoint is used to import package. - -==== Example - -[,tabs] -==== -Sample Request:: -+ --- -[source,bash] ----- -curl -X POST 'localhost:14240/gsql/v1/packages/import/pkg' ----- --- -Sample Response:: -+ --- -[source.wrap,console] ----- -{"error":false,"message":"Successfully import package pkg."} ----- --- -==== - -''' - -=== call template query - -`POST /gsql/v1/library/{functionName}` - -This endpoint is used to call template query. - -==== Parameters: - -//[width="100%",cols="25%,25%,50%",options="header",] -[%autowidth] -|=== -| Name | Required | Description - -| `graph` -| yes -| the function under which graph - -| `functionName` -| yes -| the function name to call -|=== - -==== Example - -[,tabs] -==== -Sample Request:: -+ --- -[source,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:: -+ --- -[source.wrap,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}` - -This endpoint is used to get template query's information. - -==== Parameters: - -[%autowidth] -|=== -| 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 - -[,tabs] -==== -Sample Request:: -+ --- -[source,bash] ----- -curl -H 'Content-Type: application/json' -X GET 'localhost:14240/gsql/v1/library/printVertex' ----- --- -Sample Response:: -+ --- -[source.wrap,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` - -This endpoint is used to execute any GSQL command asynchronously or synchronously. - -==== Parameters: - -[%autowidth] -|=== -| 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: -[,tabs] -==== -Sample Request:: -+ --- -[source,bash] ----- -curl -X POST -H "content-type: text/plain" "http://localhost:14240/gsql/v1/statements" -d 'ls' ----- --- -Sample Response:: -+ --- -[source.wrap,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}` - -This endpoint is used to check status of asynchronous request with requestId. - -==== Parameters: - -None - -==== Example: -[,tabs] -==== -Sample Request:: -+ --- -[source,bash] ----- -curl -X GET -H "content-type: application/json" "http://localhost:14240/gsql/v1/statements/00000000006.317280417" ----- --- -Sample Response:: -+ --- -[source.wrap,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` - -This endpoint is used to cancel an asynchronous request with requestId. - -==== Parameters: - -None - -==== Example: -[,tabs] -==== -Sample Request:: -+ --- -[source,bash] ----- -curl -X PUT -H "content-type: application/json" "http://localhost:14240/gsql/v1/statements/00000000006.317280417/cancel" ----- --- -Sample Response:: -+ --- -[source.wrap,console] ----- -{ -"error":false, -"message":"Successfully aborted request 00000000006.317280417", -} ----- --- -==== - -''' - -=== recover gdict catalog - -`POST /gsql/v1/schema/recover` - -This endpoint is used to recover catalog. - -==== Parameters: - -None - -==== Example: -[,tabs] -==== -Sample Request:: -+ --- -[source,bash] ----- -curl -X POST -H "content-type: text/plain" "http://localhost:14240/gsql/v1/schema/recover" ----- --- -Sample Response:: -+ --- -[source.wrap,console] ----- -{"error":false,"message":"Recover schema succeed!"} ----- --- -==== - -''' -=== validate graph schema - -`POST /gsql/v1/schema/check` - -This endpoint is used to validate graph schema. - -==== Parameters: - -None - -==== Example: -[,tabs] -==== -Sample Request:: -+ --- -[source,bash] ----- -curl -X POST -H "content-type: text/plain" "http://localhost:14240/gsql/v1/schema/check" ----- --- -Sample Response:: -+ --- -[source.wrap,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 xref:gsql-ref:ddl-and-loading:running-a-loading-job.adoc#_clear_graph_store[CLEAR GRAPH STORE]. - -[WARNING] -==== -This operation is not reversible. -The deleted data cannot be recovered. -==== - -==== Example: - -[,tabs] -==== -Sample Request:: -+ --- -[source,bash] ----- -curl -H 'Content-Type: application/json' -X GET 'http://localhost:14240/gsql/v1/clear-store' ----- --- -Sample Response:: -+ --- -[source.wrap,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: - -//[width="100%",cols="25%,25%,50%",options="header",] -[%autowidth] -|=== -| Name | Required | Description - -| `verbose` -| no -| `bool` type, `true` will print detail info. -|=== - -==== Example: - -[,tabs] -==== -Sample Request:: -+ --- -[source,bash] ----- -curl -H 'Content-Type: text/plain' -X GET 'http://localhost:14240/gsql/v1/version?verbose=true' ----- --- -Sample Response:: -+ --- -[source.wrap,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` - -This endpoint is used to drop all. - -[WARNING] -==== -This operation is not reversible. -The deleted data cannot be recovered. -==== - -==== Example - -[,tabs] -==== -Sample Request:: -+ --- -[source,bash] ----- -curl -H 'Content-Type: application/json' -X GET 'localhost:14240/gsql/v1/drop-all' ----- --- -Sample Response:: -+ --- -[source.wrap,console] ----- -{"error":false,"message":"Successfully dropped all."} ----- --- -==== - -''' - -=== graph export - -`POST /gsql/v1/db-export` - -This endpoint is used to export database. - -==== Example - -[,tabs] -==== -Sample Request:: -+ --- -[source,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:: -+ --- -[source.wrap,console] ----- -{"error":false,"message":"Successfully exported database."} ----- --- -==== - -''' - -=== graph import - -`POST /gsql/v1/db-import` - -This endpoint is used to import database. - -==== Example - -[,tabs] -==== -Sample Request:: -+ --- -[source,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:: -+ --- -[source.wrap,console] ----- -{"error":false,"message":"Successfully imported database."} ----- --- -==== - -''' - -== Security - -=== create new JWT token - -`POST /gsql/v1/tokens` - -This endpoint is used to create a new JWT token. - -==== Payload: - -//[width="100%",cols="25%,25%,50%",options="header",] -[%autowidth] -|=== -| 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 - -[,tabs] -==== -Sample Request:: -+ --- -[source,bash] ----- -curl -H 'Content-Type: application/json' -X POST 'localhost:14240/gsql/v1/tokens' ----- --- -Sample Response:: -+ --- -[source.wrap,console] ----- -{"expiration":"Wed Jul 10 06:12:47 UTC 2024","error":false,"message":"Generate new JWT token successfully.","token":"eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJ0aWdlcmdyYXBoIiwiaWF0IjoxNzE5OTg3MTYyLCJleHAiOjE3MjA1OTE5NjcsImlzcyI6IlRpZ2VyR3JhcGgiLCJncmFwaCI6InBvY19ncmFwaCJ9.w4ms-si5egtbhI2Cms7uL1qUU8oG0S08KIiaG_VL3Fs"} ----- --- -==== - -''' - -=== drop JWT tokens - -`DELETE /gsql/v1/tokens` - -This endpoint is used to drop specific a list of tokens. - -==== Parameters: - -//[width="100%",cols="25%,25%,50%",options="header",] -[%autowidth] -|=== -| Name | Required | Description - -| `clear` -| no -| default: false, true means clear out the current block list. -|=== - -==== Example - -[,tabs] -==== -Sample Request:: -+ --- -[source,bash] ----- -curl -H 'Content-Type: application/json' -X DELETE 'localhost:14240/gsql/v1/tokens' -d {"tokens": "$token1,$token2"} ----- --- -Sample Response:: -+ --- -[source.wrap,console] ----- -{"error":false,"message":"Successfully dropped the specified JWT tokens"} ----- --- -==== - -''' - -=== check JWT token - -`POST /gsql/v1/tokens/check` - -This endpoint is used to check JWT token is valid or not. - -==== Example - -[,tabs] -==== -Sample Request:: -+ --- -[source,bash] ----- -curl -H 'Content-Type: application/json' -X POST 'localhost:14240/gsql/v1/tokens/check' -d {"token": "$token1"} ----- --- -Sample Response:: -+ --- -[source.wrap,console] ----- -{"error":false,"message":"The token eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJ0aWdlcmdyYXBoIiwiaWF0IjoxNzE5OTg3MTYyLCJleHAiOjE3MjA1OTE5NjcsImlzcyI6IlRpZ2VyR3JhcGgiLCJncmFwaCI6InBvY19ncmFwaCJ9.w4ms-si5egtbhI2Cms7uL1qUU8oG0S08KIiaG_VL3Fs verification succeed."} ----- --- -==== - -''' - -=== create secret - -`POST /gsql/v1/secrets` - -This endpoint is used to create a secret. - -==== Parameters: - -//[width="100%",cols="25%,25%,50%",options="header",] -[%autowidth] -|=== -| 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 - -[,tabs] -==== -Sample Request:: -+ --- -[source,bash] ----- -curl -H 'Content-Type: application/json' -X POST 'localhost:14240/gsql/v1/secrets?alias=s1' ----- --- -Sample Response:: -+ --- -[source.wrap,console] ----- -{"error":false,"message":"","results":{"alias":"s1","value":"59ccqdlqmkfcqjl99u2jv4qt2telmeoj"}} ----- --- -==== - -''' - -=== show secrets - -`GET /gsql/v1/secrets` - -This endpoint is used to show secrets for the user. - -==== Parameters: - -//[width="100%",cols="25%,25%,50%",options="header",] -[%autowidth] -|=== -| 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 - -[,tabs] -==== -Sample Request:: -+ --- -[source,bash] ----- -curl -H 'Content-Type: application/json' -X GET 'localhost:14240/gsql/v1/secrets' ----- --- -Sample Response:: -+ --- -[source.wrap,console] ----- -{"error":false,"message":"","results":{"alias":"s1","value":"59ccqdlqmkfcqjl99u2jv4qt2telmeoj"}} ----- --- -==== - -''' - -=== delete secrets - -`DELETE /gsql/v1/secrets` - -This endpoint is used to delete the secrets of the user. - -==== Parameters: - -[%autowidth] -|=== -| 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 - -[,tabs] -==== -Sample Request:: -+ --- -[source,bash] ----- -curl -H 'Content-Type: application/json' -X DELETE 'localhost:14240/gsql/v1/secrets' -d '{"secrets":[$secret1,$secret2]}' ----- --- -Sample Response:: -+ --- -[source.wrap,console] ----- -{"error":false,"message":"Successfully removed the secrets for user tigergraph."} ----- --- -==== - -''' - -=== get secret by alias - -`GET /gsql/v1/secrets/{alias}` - -This endpoint is used to get the secrets by its alias name. - -==== Parameters: - -[%autowidth] -|=== -| 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 - -[,tabs] -==== -Sample Request:: -+ --- -[source,bash] ----- -curl -H 'Content-Type: application/json' -X GET 'localhost:14240/gsql/v1/secrets/s2' ----- --- -Sample Response:: -+ --- -[source.wrap,console] ----- -{"error":false,"message":"","results":{"alias":"s2","value":"g2ea27q79tes6nsark3k3ecp718rp4ej"}} ----- --- -==== - -''' - -=== drop secret by alias - -`DELETE /gsql/v1/secrets/{alias}` - -This endpoint is used to delete the secret of the user by its alias name. - -==== Parameters: - -[%autowidth] -|=== -| 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 - -[,tabs] -==== -Sample Request:: -+ --- -[source,bash] ----- -curl -H 'Content-Type: application/json' -X DELETE 'localhost:14240/gsql/v1/secrets/s2' ----- --- -Sample Response:: -+ --- -[source.wrap,console] ----- -{"error":false,"message":"Successfully removed the secrets for user tigergraph."} ----- --- -==== - -''' - -=== retrieve a group by id using gsql format - -`GET /gsql/v1/groups/{id}` - -This endpoint is used to retrieve a group by id response scim format or gsql format JSON. - -==== Parameters: - -None - -==== Example: -[,tabs] -==== -Sample Request:: -+ --- -[source,bash] ----- -curl -X GET "http://localhost:14240/gsql/v1/groups/g1" ----- --- -Sample Response:: -+ --- -[source.wrap,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` - -This endpoint is used to retrieve groups response gsql format JSON. - -==== Parameters: - -[%autowidth] -|=== -| 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: -[,tabs] -==== -Sample Request:: -+ --- -[source,bash] ----- -curl -X GET "Content-type: text/plain" "http://localhost:14240/gsql/v1/groups" ----- --- -Sample Response:: -+ --- -[source.wrap,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` - -This endpoint is used to create a group using gsql format. - -==== Parameters: - -None - -==== Example: -[,tabs] -==== -Sample Request:: -+ --- -[source,bash] ----- -curl -X POST "Content-type: application/json" "http://localhost:14240/gsql/v1/groups" -d '{"groupName":"g4","proxyRule":"group=tech-department"}' ----- --- -Sample Response:: -+ --- -[source.wrap,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` - -This endpoint is used to update a group. - -==== Parameters: - -None - -==== Example: -[,tabs] -==== -Sample Request:: -+ --- -[source,bash] ----- -curl -X PUT "Content-type: application/json" "http://localhost:14240/gsql/v1/groups" -d '{"name": "g1", "rule": ""group=tech-department""}' ----- --- -Sample Response:: -+ --- -[source.wrap,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}` - -This endpoint is used to drop one group by name. - -==== Parameters: - -None - -==== Example: -[,tabs] -==== -Sample Request:: -+ --- -[source,bash] ----- -curl -X DELETE "Content-type: application/json" "http://localhost:14240/gsql/v1/groups/g1" ----- --- -Sample Response:: -+ --- -[source.wrap,console] ----- -{"error":false,"message":"Successfully dropped group g1"} ----- --- -==== - -''' - -=== drop groups using gsql format - -`POST /gsql/v1/groups` - -This endpoint is used to drop groups. - -==== Parameters: - -//[width="100%",cols="25%,25%,50%",options="header",] -[%autowidth] -|=== -| 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: -[,tabs] -==== -Sample Request:: -+ --- -[source,bash] ----- -curl -X POST "Content-type: application/json" "http://localhost:14240/gsql/v1/groups?action=delete" -d '{"groupNames":["g1"]}' ----- --- -Sample Response:: -+ --- -[source.wrap,console] ----- -{"error":false,"message":"Successfully dropped groups: [g1]"} ----- --- -==== - -''' - -=== retrieve a user by id using gsql format - -`GET /gsql/v1/users/{id}` - -This endpoint is used to retrieve a user by id respond gsql format. - -==== Parameters: - -None - -==== Example: -[,tabs] -==== -Sample Request:: -+ --- -[source,bash] ----- -curl -X GET "http://localhost:14240/gsql/v1/users/u1" ----- --- -Sample Response:: -+ --- -[source.wrap,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` - -This endpoint is used to update a user. - -==== Parameters: - -None - -==== Example: -[,tabs] -==== -Sample Request:: -+ --- -[source,bash] ----- -curl -X PUT -H "Content-type: application/json" "http://localhost:14240/gsql/v1/users" -d '{"name": "tigergraph", "password": "123"}' ----- --- -Sample Response:: -+ --- -[source.wrap,console] ----- -{"error": false, "message": "Successfully updated user tigergraph"} ----- --- -==== - -''' - -=== drop users for gsql format - -`POST /gsql/v1/users` - -This endpoint is used to drop users. - -==== Parameters: - -//[width="100%",cols="25%,25%,50%",options="header",] -[%autowidth] -|=== -| 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: -[,tabs] -==== -Sample Request:: -+ --- -[source,bash] ----- -curl -X POST -H "Content-type: application/json" "http://localhost:14240/gsql/v1/users?action=delete" -d ' {"userNames":["u1"]}' ----- --- -Sample Response:: -+ --- -[source.wrap,console] ----- -{"error":false,"message":"Successfully dropped users: [u1]"} ----- --- -==== - -''' - -=== drop a user using gsql format - -`DELETE /gsql/v1/users/{id}` - -This endpoint is used to drop a user. - -==== Parameters: - -None - -==== Example: -[,tabs] -==== -Sample Request:: -+ --- -[source,bash] ----- -curl -X DELETE -H "Content-type: application/json" "http://localhost:14240/gsql/v1/users/u1" ----- --- -Sample Response:: -+ --- -[source.wrap,console] ----- -{"error":false,"message":"Successfully dropped user u1"} ----- --- -==== - -''' - -=== create a user using gsql format - -`POST /gsql/v1/users` - -This endpoint is used to create a user using gsql format. - -==== Parameters: - -None - -==== Example: -[,tabs] -==== -Sample Request:: -+ --- -[source,bash] ----- -curl -X POST -H "Content-type: application/json" "http://localhost:14240/gsql/v1/users" -d ' {"password":"tiger123","username":"user2"}' ----- --- -Sample Response:: -+ --- -[source.wrap,console] ----- -{"error":false,"message":"Successfully created user user2"} ----- --- -==== - -''' - -=== retrieve users using gsql format - -`GET /gsql/v1/users` - -This endpoint is used to retrieve users response gsql format JSON. - -==== Parameters: - -[%autowidth] -|=== -| 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: -[,tabs] -==== -Sample Request:: -+ --- -[source,bash] ----- -curl -X GET -H "Content-type: application/json" "http://localhost:14240/gsql/v1/users" ----- --- -Sample Response:: -+ --- -[source.wrap,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","ACCESS_TAG","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` - -This endpoint is used to list all built-in privileges. - -==== Example: - -[,tabs] -==== -Sample Request:: -+ --- -[source,bash] ----- -curl -H 'Content-Type: application/json' -X GET "http://localhost:14240/gsql/v1/privileges" ----- --- -Sample Response:: -+ --- -[source.wrap,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":"ACCESS_TAG"},{"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` - -This endpoint is used to grant RABC privileges to specific roles. - -==== Parameters: - -//[width="100%",cols="25%,25%,50%",options="header",] -[%autowidth] -|=== -| 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: - -[,tabs] -==== -Sample Request:: -+ --- -[source,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:: -+ --- -[source.wrap,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` - -This endpoint is used to revoke RABC privileges from specific roles - -==== Parameters: - -//[width="100%",cols="25%,25%,50%",options="header",] -[%autowidth] -|=== -| 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: - -[,tabs] -==== -Sample Request:: -+ --- -[source,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:: -+ --- -[source.wrap,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: - -[,tabs] -==== -Sample Request:: -+ --- -[source,bash] ----- -curl -H 'Content-Type: application/json' -X GET "http://localhost:14240/gsql/v1/roles" ----- --- -Sample Response:: -+ --- -[source.wrap,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: - -//[width="100%",cols="25%,25%,50%",options="header",] -[%autowidth] -|=== -| Name | Required | Description - -| `graph` -| no -| in which graph to create local roles, -or create global roles if the parameter is missing -|=== - -==== Example: - -[,tabs] -==== -Sample Request:: -+ --- -[source,bash] ----- -curl -H 'Content-Type: application/json' -X POST "http://localhost:14240/gsql/v1/roles?graph=financialGraph" -d "{"roles":["r1", "r2"]}" ----- --- -Sample Response:: -+ --- -[source.wrap,console] ----- -{"error":false,"message":"","results":"Successfully created local roles on graph 'financialGraph': [r1, r2]."} ----- --- -==== - -''' - -=== Delete roles - -`DELETE /gsql/v1/roles` - -==== Parameters: - -//[width="100%",cols="25%,25%,50%",options="header",] -[%autowidth] -|=== -| 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: - -[,tabs] -==== -Sample Request:: -+ --- -[source,bash] ----- -curl -H 'Content-Type: application/json' -X DELETE "http://localhost:14240/gsql/v1/roles?graph=financialGraph&role=r1,r2" ----- --- -Sample Response:: -+ --- -[source.wrap,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: - -[,tabs] -==== -Sample Request:: -+ --- -[source,bash] ----- -curl -H 'Content-Type: application/json' -X GET "http://localhost:14240/gsql/v1/roles/r1" ----- --- -Sample Response:: -+ --- -[source.wrap,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: - -[,tabs] -==== -Sample Request:: -+ --- -[source,bash] ----- -curl -H 'Content-Type: application/json' -X DELETE "http://localhost:14240/gsql/v1/roles/r1" ----- --- -Sample Response:: -+ --- -[source.wrap,console] ----- -{"error":false,"message":"","results":"Successfully dropped roles: [r1]."} ----- --- -==== - -''' - -=== grant role(s) to user(s) - -`POST /gsql/v1/roles/grant` - -This endpoint is used to grant roles to specific users - -==== Parameters: - -//[width="100%",cols="25%,25%,50%",options="header",] -[%autowidth] -|=== -| 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: - -[,tabs] -==== -Sample Request:: -+ --- -[source,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:: -+ --- -[source.wrap,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` - -This endpoint is used to revoke roles from specific users - -==== Parameters: - -//[width="100%",cols="25%,25%,50%",options="header",] -[%autowidth] -|=== -| 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: - -[,tabs] -==== -Sample Request:: -+ --- -[source,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:: -+ --- -[source.wrap,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}` - -This endpoint is used to retrieve a group by id response scim format. - -==== Parameters: - -None - -==== Example: -[,tabs] -==== -Sample Request:: -+ --- -[source,bash] ----- -curl -X GET "http://localhost:14240/gsql/scim/v2/Groups/g2" ----- --- -Sample Response:: -+ --- -[source.wrap,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` - -This endpoint is used to retrieve groups response scim format. - -==== Parameters: - -//[width="100%",cols="25%,25%,50%",options="header",] -[%autowidth] -|=== -| 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: -[,tabs] -==== -Sample Request:: -+ --- -[source,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:: -+ --- -[source.wrap,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` - -This endpoint is used to create a group using scim format. - -==== Parameters: - -None - -==== Example: -[,tabs] -==== -Sample Request:: -+ --- -[source,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:: -+ --- -[source.wrap,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}` - -This endpoint is used to update a group. - -==== Parameters: - -None - -==== Example: -[,tabs] -==== -Sample Request:: -+ --- -[source,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:: -+ --- -[source.wrap,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}` - -This endpoint is used to drop one group by name. - -==== Parameters: - -None - -==== Example: -[,tabs] -==== -Sample Request:: -+ --- -[source,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:: -+ --- -[source.wrap,console] ----- -{"error":false,"message":"Successfully dropped group g1"} ----- --- -==== - -''' - -=== drop groups using scim format - -`POST /gsql/scim/v2/Groups` - -This endpoint is used to drop groups. - -==== Parameters: - -//[width="100%",cols="25%,25%,50%",options="header",] -[%autowidth] -|=== -| 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: -[,tabs] -==== -Sample Request:: -+ --- -[source,bash] ----- -curl -X POST "Content-type: application/json" "http://localhost:14240/gsql/scim/v2/Groups?action=delete" -d '{"groupNames":["g1"]}' ----- --- -Sample Response:: -+ --- -[source.wrap,console] ----- -{"error":false,"message":"Successfully dropped groups: [g1]"} ----- --- -==== - -''' - -=== retrieve a user by id using scim format - -`GET /gsql/scim/v2/Users/{id}` - -This endpoint is used to retrieve a user by id respond with scim format. - -==== Parameters: - -None - -==== Example: -[,tabs] -==== -Sample Request:: -+ --- -[source,bash] ----- -curl -X GET "http://localhost:14240/gsql/scim/v2/Users/u1" ----- --- -Sample Response:: -+ --- -[source.wrap,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}` - -This endpoint is used to update a user. - -==== Parameters: - -None - -==== Example: -[,tabs] -==== -Sample Request:: -+ --- -[source,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:: -+ --- -[source.wrap,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` - -This endpoint is used to drop users. - -==== Parameters: - -//[width="100%",cols="25%,25%,50%",options="header",] -[%autowidth] -|=== -| 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: -[,tabs] -==== -Sample Request:: -+ --- -[source,bash] ----- -curl -X POST -H "Content-type: application/json" "http://localhost:14240/gsql/scim/v2/Users?action=delete" -d ' {"userNames":["u1"]}' ----- --- -Sample Response:: -+ --- -[source.wrap,console] ----- -{"error":false,"message":"Successfully dropped users: [u1]"} ----- --- -==== - -''' - -=== drop a user using scim format - -`DELETE /gsql/scim/v2/Users/{id}` - -This endpoint is used to drop a user. - -==== Parameters: - -None - -==== Example: -[,tabs] -==== -Sample Request:: -+ --- -[source,bash] ----- -curl -X DELETE -H "Content-type: application/json" "http://localhost:14240/gsql/scim/v2/Users/u1" ----- --- -Sample Response:: -+ --- -[source.wrap,console] ----- -{"error":false,"message":"Successfully dropped user u1"} ----- --- -==== - -''' - -=== create a user using scim format - -`POST /gsql/scim/v2/Users` - -This endpoint is used to create a user using scim format. - -==== Parameters: - -None - -==== Example: -[,tabs] -==== -Sample Request:: -+ --- -[source,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:: -+ --- -[source.wrap,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` - -This endpoint is used to retrieve users response scim format. - -==== Parameters: - -//[width="100%",cols="25%,25%,50%",options="header",] -[%autowidth] -|=== -| 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: -[,tabs] -==== -Sample Request:: -+ --- -[source,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:: -+ --- -[source.wrap,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` - -This endpoint is used to fetch cardinality statistics. - -==== Parameters: - -//[width="100%",cols="25%,25%,50%",options="header",] -[%autowidth] -|=== -| Name | Required | Description - -| `graph` -| yes -| Get the cardinality stats of which graph -|=== - -==== Example: - -[,tabs] -==== -Sample Request:: -+ --- -[source,bash] ----- -curl -H 'Content-Type: application/json' -X GET 'http://localhost:14240/gsql/v1/stats/cardinality?graph=financialGraph' ----- --- -Sample Response:: -+ --- -[source.wrap,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: - -//[width="100%",cols="25%,25%,50%",options="header",] -[%autowidth] -|=== -| 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: - -[,tabs] -====== -Sample Request 1:: -+ --- -[source,bash] ----- -curl -H 'Content-Type: application/json' -X POST 'http://localhost:14240/gsql/v1/stats/cardinality?graph=financialGraph&vertex=Account' ----- --- -Sample Response 1:: -+ --- -[source.wrap,console] ----- -{"error": false,"message": "successfully persisted statistics"} ----- --- -====== - -[,tabs] -====== -Sample Request 2:: -+ --- -[source,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:: -+ --- -[source.wrap,console] ----- -{"error": false,"message": "successfully persisted statistics"} ----- --- -====== - -==== 2) Persist user defined cardinality statistics to storage. - -==== Parameters: - -//[width="100%",cols="25%,25%,50%",options="header",] -[%autowidth] -|=== -| Name | Required | Description - -| `graph` -| yes -| Persist the cardinality stats to which graph -|=== - -===== Example: - -[,tabs] -====== -Sample Request:: -+ --- -[source,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:: -+ --- -[source.wrap,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` - -This endpoint is used to remove cardinality statistics from storage. - -==== Parameters: - -//[width="100%",cols="25%,25%,50%",options="header",] -[%autowidth] -|=== -| Name | Required | Description - -| `graph` -| yes -| Delete the cardinality stats of indicated graph from storage -|=== - -==== Example: - -[,tabs] -==== -Sample Request:: -+ --- -[source,bash] ----- -curl -H 'Content-Type: application/json' -X DELETE 'http://localhost:14240/gsql/v1/stats/cardinality?graph=financialGraph' ----- --- -Sample Response:: -+ --- -[source.wrap,console] ----- -{"error":false,"message":"successfully deleted statistics"} ----- --- -==== - -''' - -=== get histogram statistics - -`GET /gsql/v1/stats/histogram` - -This endpoint is used to fetch histogram statistics. - -==== Example: - -[,tabs] -==== -Sample Request:: -+ --- -[source,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:: -+ --- -[source.wrap,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` - -This endpoint is used to persist new histogram statistics to storage. - -==== Example: - -[,tabs] -===== -Sample Request:: -+ --- -[source,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:: -+ --- -[source.wrap,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` - -This endpoint is used to remove histogram statistics from storage. - -==== Example: - -[,tabs] -==== -Sample Request:: -+ --- -[source,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:: -+ --- -[source.wrap,console] ----- -{"error": false,"message": "","results": "Deleting any histogram(s) for G.E1.a"} ----- --- -==== - -''' - - -== User Defined Objects - -=== list all tuples - -`GET /gsql/v1/udt/tuples` - -This endpoint is used to get all tuples. - -==== Example - -[,tabs] -==== -Sample Request:: -+ --- -[source,bash] ----- -curl -H 'Content-Type: application/json' -X GET 'localhost:14240/gsql/v1/udt/tuples' ----- --- -Sample Response:: -+ --- -[source.wrap,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}` - -This endpoint is used to get tuple by its name. - -==== Parameters: - -[%autowidth] -|=== -| Name | Required | Description - -| `tupleName` -| yes -| the tuple name to get information -|=== - -==== Example - -[,tabs] -==== -Sample Request:: -+ --- -[source,bash] ----- -curl -H 'Content-Type: application/json' -X GET 'localhost:14240/gsql/v1/udt/tuples/TestTup' ----- --- -Sample Response:: -+ --- -[source.wrap,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` - -This endpoint is used to create a tuple. - -==== Example - -[,tabs] -==== -Sample Request:: -+ --- -[source,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:: -+ --- -[source.wrap,console] ----- -{"error":false,"message":"Successfully create tuples: TestTup."} ----- --- -==== - -''' - -=== delete multiple tuples - -`DELETE /gsql/v1/udt/tuples` - -This endpoint is used to delte multiple tuples. - -==== Parameters: - -[%autowidth] -|=== -| Name | Required | Description - -| `tupleName` -| yes -| the tuple names to be dropped -|=== - -==== Example - -[,tabs] -==== -Sample Request:: -+ --- -[source,bash] ----- -curl -H 'Content-Type: application/json' -X DELETE 'localhost:14240/gsql/v1/udt/tuples?tupleName=TestTuple' ----- --- -Sample Response:: -+ --- -[source.wrap,console] ----- -{"error":false,"message":"Successfully dropped userDefinedTuple: [TestTup]."} ----- --- -==== - -''' - -=== delete one tuple - -`DELETE /gsql/v1/udt/tuples/{tupleName}` - -This endpoint is used to delete one tuple by its name. - -==== Example - -[,tabs] -==== -Sample Request:: -+ --- -[source,bash] ----- -curl -H 'Content-Type: application/json' -X DELETE 'localhost:14240/gsql/v1/udt/tuples/TestTuple' ----- --- -Sample Response:: -+ --- -[source.wrap,console] ----- -{"error":false,"message":"Successfully dropped userDefinedTuple: [TestTup]."} ----- --- -==== - -''' - -=== list all accumulators - -`GET /gsql/v1/udt/accum` - -This endpoint is used to get all accumulators. - -==== Example - -[,tabs] -==== -Sample Request:: -+ --- -[source,bash] ----- -curl -H 'Content-Type: application/json' -X GET 'localhost:14240/gsql/v1/udt/accum' ----- --- -Sample Response:: -+ --- -[source.wrap,console] ----- -{"error":false,"message":"","results":[{"myGroup":"GroupByAccum b> myGroup\n"}]} ----- --- -==== - -''' - -=== list one accumulator - -`GET /gsql/v1/udt/accum/{accumName}` - -This endpoint is used to get one accumulator by its name. - -==== Example - -[,tabs] -==== -Sample Request:: -+ --- -[source,bash] ----- -curl -H 'Content-Type: application/json' -X GET 'localhost:14240/gsql/v1/udt/accum/myGroup' ----- --- -Sample Response:: -+ --- -[source.wrap,console] ----- -{"error":false,"message":"","results":[{"myGroup":"GroupByAccum b> myGroup\n"}]} ----- --- -==== - -''' - -=== create accumulators - -`POST /gsql/v1/udt/accum` - -This endpoint is used to create one accumulator. - -==== Example - -[,tabs] -==== -Sample Request:: -+ --- -[source,bash] ----- -curl -H 'Content-Type: application/json' -X POST 'localhost:14240/gsql/v1/udt/accum' -d '{"AccumString":"typedef GroupByAccum or typedef HeapAccum"}' ----- --- -Sample Response:: -+ --- -[source.wrap,console] ----- -{"error":false,"message":"Successfully create accumulator."} ----- --- -==== - -''' - -=== delete mulitple accumulators - -`DELETE /gsql/v1/udt/accum` - -This endpoint is used to delete multiple accumulators. - -==== Parameters: - -[%autowidth] -|=== -| Name | Required | Description - -| `accumName` -| yes -| the accumulator names to drop -|=== - -==== Example - -[,tabs] -==== -Sample Request:: -+ --- -[source,bash] ----- -curl -H 'Content-Type: application/json' -X DELETE 'localhost:14240/gsql/v1/udt/accum?accumName=myGroup' ----- --- -Sample Response:: -+ --- -[source.wrap,console] ----- -{"error":false,"message":"Successfully dropped accumulator: [myGroup]."} ----- --- -==== - -''' - -=== delete one accumulator - -`DELETE /gsql/v1/udt/accum/{accumName}` - -This endpoint is used to delete one accumulator. - -==== Example - -[,tabs] -==== -Sample Request:: -+ --- -[source,bash] ----- -curl -H 'Content-Type: application/json' -X DELETE 'localhost:14240/gsql/v1/udt/accum/myGroup' ----- --- -Sample Response:: -+ --- -[source.wrap,console] ----- -{"error":false,"message":"Successfully dropped accumulator: [myGroup]."} ----- --- -==== - -''' - -=== download expr files - -`GET /gsql/v1/udt/files/{fileName}` - -This endpoint is used to download one file by its name, {fileName} can be one of: [tg_]ExprFunctions, [tg_]ExprUtil, TokenBank. - -==== Example - -[,tabs] -==== -Sample Request:: -+ --- -[source,bash] ----- -curl -H 'Content-Type: application/json' -X GET 'localhost:14240/gsql/v1/udt/files/TokenBank' ----- --- -Sample Response:: -+ --- -[source.wrap,console] ----- -{"error":false,"results": {"TokenBank": ""}} ----- --- -==== - -''' - -=== download all files - -`GET /gsql/v1/udt/files` - -This endpoint is used to get all files. - -==== Example - -[,tabs] -==== -Sample Request:: -+ --- -[source,bash] ----- -curl -H 'Content-Type: application/json' -X GET 'localhost:14240/gsql/v1/udt/files' ----- --- -Sample Response:: -+ --- -[source.wrap,console] ----- -{"error":false,"results": {"TokenBank": "TokenBank File Content", "ExprFunctions": "ExprFunctions file content", "ExprUtil": "", "tg_ExprFunctions": "", "tg_ExprUtil": ""}} ----- --- -==== - -''' - -=== upload one file - -`PUT /gsql/v1/udt/files/{fileName}` - -This endpoint is used to upload file. - -==== Example - -[,tabs] -==== -Sample Request:: -+ --- -[source,bash] ----- -curl -H 'Content-Type: text/plain' -X PUT 'localhost:14240/gsql/v1/udt/files/TokenBank' -d '' ----- --- -Sample Response:: -+ --- -[source.wrap,console] ----- -{"error":false,"message": "Successfully update file: TokenBank"} ----- --- -==== - -''' - -=== upload file - -`PUT /gsql/v1/udt/files` - -This endpoint is used to upload all files. - -==== Example - -[,tabs] -==== -Sample Request:: -+ --- -[source,bash] ----- -curl -H 'Content-Type: application/json' -X PUT 'localhost:14240/gsql/v1/udt/files' -d '{"files":[{"Name":"ExprUtil","Content":""}]}' ----- --- -Sample Response:: -+ --- -[source.wrap,console] ----- -{"error":false,"message": "All files get updated: [TokenBank, ExprFunctions]."} ----- --- -==== - -''' - -=== get token bank functions - -`GET /gsql/v1/udt/token-functions/{functionName}` - -This endpoint is used to get function content by its name. - -==== Example - -[,tabs] -==== -Sample Request:: -+ --- -[source,bash] ----- -curl -X GET 'localhost:14240/gsql/v1/udt/token-functions/_Concat' ----- --- -Sample Response:: -+ --- -[source.wrap,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` - -This endpoint is used to get all token bank functions. - -==== Example - -[,tabs] -==== -Sample Request:: -+ --- -[source,bash] ----- -curl -X GET 'localhost:14240/gsql/v1/udt/token-functions' ----- --- -Sample Response:: -+ --- -[source.wrap,console] ----- -{"error":false,"message":"","results":[{"code":"token bank function code","name":"_Concat","returnType":"string"}]} ----- --- -==== - -''' diff --git a/modules/API/pages/index.adoc.bak b/modules/API/pages/index.adoc.bak deleted file mode 100644 index d38c23e7..00000000 --- a/modules/API/pages/index.adoc.bak +++ /dev/null @@ -1,41 +0,0 @@ -= GSQL SERVER REST API -:description: Overview of GSQL SERVER's REST API. -:pp: {plus}{plus} -//:page-aliases: tigergraph-server:API:intro.adoc, tigergraph-server:api:intro.doc - -This user guide provides information on how to engage with our REST APIs: the introduction section explains how to send requests, pass parameters, and format request bodies, while xref:gsql-endpoints.adoc[] describes in detail each endpoint and its input and output. - -To submit a request, send an HTTP request to the NGINX server or the GSQL server. -By default, the GSQL server listens for requests at port 8123 and the NGINX server listens on port 14240. -A request must include the following specifications: - -* The request method (`GET`, `POST`, `PUT`, or `DELETE`) -* The endpoint address -* Any required or optional request parameters in URL encoding -* For `POST` requests, a data payload (i.e., request body) in JSON encoding unless otherwise specified -* In some cases, request header parameters - -For requests sent to the GSQL server, TigerGraph user credentials must be provided for the request to be accepted. - - -== `curl` options - -Request examples in this guide are made using https://curl.se/docs/manpage.html[`curl`]. Below is a list of `curl` options used in our code examples: - -* `-d ` - ** Sends the specified data in a `POST` request to the HTTP server in the same way that a browser does when a user has filled in an HTML form and presses the submit button. This will cause curl to pass the data to the server using the content-type `application/x-www-form-urlencoded`. - ** If the data starts with the character @, the rest should specify the filepath from which to read the data. The command `curl -d @foobar` will read data from a file named `foobar`. -* `--data-binary ` - ** Sends data with a `POST` request exactly as specified with no extra processing. -* `--fail` - ** Makes curl fail silently (no output at all) on server errors. - ** This is mostly done to enable scripts etc. to better deal with failed attempts. In normal cases when an HTTP server fails to deliver a document, it returns an HTML document stating so (which often also describes why and more). This flag will prevent curl from outputting that and return error 22. -* `-H
` - ** Extra header to include in the request when sending HTTP to a server. Any number of extra headers can be specified. - ** TigerGraph APIs use headers to specify xref:API:index.adoc#_size_and_time_limits[size and time limits], as well as to provide RESTPP xref:authentication.adoc#_restpp_server_requests[authentication] tokens. -* `-s` - ** Silent or quiet mode. Don't show a progress meter or error messages. It will still output the data you ask for, potentially even to the terminal/stdout unless you redirect it. -* `-u ` - ** Submits the specified user name and password for server authentication. -* `-X ` - ** Specifies a custom request method to use when communicating with the HTTP server. If this option is not used, curl will make a `GET` request by default. diff --git a/modules/appendix/examples/computer_net/select_statement_index_sample_edges_per_source_vertex.gsql b/modules/appendix/examples/computer_net/select_statement_index_sample_edges_per_source_vertex.gsql index a2a0412f..10992b99 100644 --- a/modules/appendix/examples/computer_net/select_statement_index_sample_edges_per_source_vertex.gsql +++ b/modules/appendix/examples/computer_net/select_statement_index_sample_edges_per_source_vertex.gsql @@ -9,7 +9,7 @@ CREATE QUERY sample_ex_3() FOR GRAPH Computer_Net { start = {Computer.*}; // Sample one outgoing edge per source vertex = Random Walk - abs_sample = SELECT v FROM start:s -(:e)- :v + abs_sample = SELECT v FROM (s:start) -[e]- (v) SAMPLE 1 EDGE WHEN s.outdegree() >= 1 // sample 1 target vertex from each source vertex ACCUM @@abs_edges += (s.id -> v.id), diff --git a/modules/appendix/examples/friend_net/select_statement_index_limit_lower_bound_and_size.gsql b/modules/appendix/examples/friend_net/select_statement_index_limit_lower_bound_and_size.gsql index be153c1c..2fbfb71b 100644 --- a/modules/appendix/examples/friend_net/select_statement_index_limit_lower_bound_and_size.gsql +++ b/modules/appendix/examples/friend_net/select_statement_index_limit_lower_bound_and_size.gsql @@ -1,7 +1,7 @@ CREATE QUERY limit_ex_2 (INT j, INT k) FOR GRAPH Friend_Net { start = {Person.*}; - result2 = SELECT v FROM start:v + result2 = SELECT v FROM (v:start) ORDER BY v.id LIMIT j, k; diff --git a/modules/appendix/examples/friend_net/select_statement_index_limit_with_offset.gsql b/modules/appendix/examples/friend_net/select_statement_index_limit_with_offset.gsql index 7fb99e05..50c883e4 100644 --- a/modules/appendix/examples/friend_net/select_statement_index_limit_with_offset.gsql +++ b/modules/appendix/examples/friend_net/select_statement_index_limit_with_offset.gsql @@ -1,7 +1,7 @@ CREATE QUERY limit_ex_3 (INT j, INT k) FOR GRAPH Friend_Net { start = {Person.*}; - result3 = SELECT v FROM start:v + result3 = SELECT v FROM (v:start) ORDER BY v.id LIMIT k OFFSET j; diff --git a/modules/appendix/examples/friend_net/select_statement_index_limt_by.gsql b/modules/appendix/examples/friend_net/select_statement_index_limt_by.gsql index 61ca402c..ef315f54 100644 --- a/modules/appendix/examples/friend_net/select_statement_index_limt_by.gsql +++ b/modules/appendix/examples/friend_net/select_statement_index_limt_by.gsql @@ -1,7 +1,7 @@ CREATE QUERY limit_ex_1 (INT k) FOR GRAPH Friend_Net { start = {Person.*}; - result1 = SELECT v FROM start:v + result1 = SELECT v FROM (v:start) ORDER BY v.id LIMIT k; diff --git a/modules/appendix/examples/friend_net/select_statement_index_order_by_descending.gsql b/modules/appendix/examples/friend_net/select_statement_index_order_by_descending.gsql index 821c57ba..5f4b412b 100644 --- a/modules/appendix/examples/friend_net/select_statement_index_order_by_descending.gsql +++ b/modules/appendix/examples/friend_net/select_statement_index_order_by_descending.gsql @@ -3,7 +3,7 @@ CREATE QUERY top_popular() FOR GRAPH Friend_Net { SumAccum @num_coworkers; start = {Person.*}; - result = SELECT v FROM start -((Friend|Coworker):e)- Person:v + result = SELECT v FROM (:start) -[e:Friend|Coworker]- (v:Person) ACCUM CASE WHEN e.type == "Friend" THEN v.@num_friends += 1 WHEN e.type == "Coworker" THEN v.@num_coworkers += 1 @@ -11,4 +11,4 @@ CREATE QUERY top_popular() FOR GRAPH Friend_Net { ORDER BY v.@num_friends DESC, v.@num_coworkers DESC; PRINT result; -} \ No newline at end of file +} diff --git a/modules/appendix/examples/ldbc_snb/select_statement_accum.gsql b/modules/appendix/examples/ldbc_snb/select_statement_accum.gsql index a2e805d8..b459ccb3 100644 --- a/modules/appendix/examples/ldbc_snb/select_statement_accum.gsql +++ b/modules/appendix/examples/ldbc_snb/select_statement_accum.gsql @@ -1,11 +1,11 @@ -CREATE QUERY accum_wrong_example() SYNTAX v2 { +CREATE QUERY accum_wrong_example() SYNTAX v3 { SumAccum @@count_total; SumAccum @active_flag = 0; result = SELECT p - FROM Person: p - (KNOWS) - Person: w + FROM (p:Person) -[:KNOWS]- (w:Person) WHERE w.lastName == "Wang" AND p.firstName == "Peter" ACCUM p.@active_flag += 1, - @@count_total += p.@active_flag; // <1> + @@count_total += p.@active_flag; // <1> PRINT @@count_total, result[result.@active_flag]; -} \ No newline at end of file +} diff --git a/modules/appendix/examples/ldbc_snb/select_statement_accum_2.gsql b/modules/appendix/examples/ldbc_snb/select_statement_accum_2.gsql index adc86908..b1ec90f8 100644 --- a/modules/appendix/examples/ldbc_snb/select_statement_accum_2.gsql +++ b/modules/appendix/examples/ldbc_snb/select_statement_accum_2.gsql @@ -1,11 +1,11 @@ -CREATE QUERY accum_example() SYNTAX v2 { +CREATE QUERY accum_example() SYNTAX v3 { SumAccum @@count_total; SumAccum @active_flag = 0; result = SELECT p - FROM Person: p - (KNOWS) - Person: w + FROM (p:Person) -[:KNOWS]- (w:Person) WHERE w.lastName == "Wang" AND p.firstName == "Peter" ACCUM p.@active_flag += 1 POST-ACCUM @@count_total += p.@active_flag; PRINT @@count_total, result[result.@active_flag]; -} \ No newline at end of file +} diff --git a/modules/appendix/examples/ldbc_snb/select_statement_index_three_post_accum_clauses.gsql b/modules/appendix/examples/ldbc_snb/select_statement_index_three_post_accum_clauses.gsql index 29228828..91771c97 100644 --- a/modules/appendix/examples/ldbc_snb/select_statement_index_three_post_accum_clauses.gsql +++ b/modules/appendix/examples/ldbc_snb/select_statement_index_three_post_accum_clauses.gsql @@ -4,8 +4,8 @@ INTERPRET QUERY () { SumAccum @cnt2; SumAccum @@global_t_count; - R = SELECT s - FROM Person:s-(Likes>) -:msg - (Has_Creator>)-Person:t + R = SELECT s + FROM (s:Person) -[:Likes]\-> (:msg) -[:Has_Creator]\-> (t:Person) WHERE s.first_name == "Viktor" AND s.last_name == "Akhiezer" AND t.last_name LIKE "S%" AND year(msg.creation_date) == 2012 ACCUM s.@cnt1 +=1 //execute this per match of the FROM pattern. @@ -13,5 +13,5 @@ INTERPRET QUERY () { POST-ACCUM t.@cnt2 +=1 // <2> POST-ACCUM(t) @@global_t_count += 1; // <3> - PRINT R [R.first_name, R.last_name, R.@cnt1, R.@cnt2]; -} \ No newline at end of file + PRINT R [R.first_name, R.last_name, R.@cnt1, R.@cnt2]; +} diff --git a/modules/appendix/examples/minimal_net/accum_bitwise.gsql b/modules/appendix/examples/minimal_net/accum_bitwise.gsql index 16794ff9..3a8d24de 100644 --- a/modules/appendix/examples/minimal_net/accum_bitwise.gsql +++ b/modules/appendix/examples/minimal_net/accum_bitwise.gsql @@ -1,28 +1,23 @@ -CREATE QUERY bitwise_accum_ex() FOR GRAPH Minimal_Net { +CREATE QUERY bitwise_accum_ex(UINT len) FOR GRAPH Minimal_Net { + BitwiseAndAccum @@bw_and; // Regular fixed-length (64 bits) + BitwiseOrAccum<80> @@bw_or_long; // Long fixed-length + BitwiseOrAccum @@bw_or_dyn; // Dynamic-length - BitwiseAndAccum @@bw_and_accum_var; // default value = 64-bits of 1 = -1 (INT) - BitwiseOrAccum @@bw_or_accum_var; // default value = 64-bits of 0 = 0 (INT)) + // Regular fixed-length + @@bw_and += 170; // 11111111 & 10101010 -> 10101010 (decimal 170) + @@bw_and += 85; // 10101010 & 01010101 -> 00000000 (decimal 0) + PRINT @@bw_and; // 0 - // 11110000 = 240 - // 00001111 = 15 - // 10101010 = 170 - // 01010101 = 85 + // Long fixed-length + @@bw_or_long += 170; // 80 bits: ...000 | ...10101010 -> ...10101010 + @@bw_or_long.clear(); // Resets to 0 (default for BitwiseOrAccum) and frees memory + @@bw_or_long += 85; // ...000 | ...01010101 -> ...01010101 (decimal 85) + PRINT @@bw_or_long; // 85 - // BitwiseAndAccum - @@bw_and_accum_var += 170; // 11111111 & 10101010 -> 10101010 - @@bw_and_accum_var += 85; // 10101010 & 01010101 -> 00000000 - PRINT @@bw_and_accum_var; // 0 + // Dynamic-length (e.g., len = 8) + @@bw_or_dyn += 170; // 00000000 | 10101010 -> 10101010 (decimal 170) + @@bw_or_dyn += 85; // 10101010 | 01010101 -> 11111111 (decimal 255) + PRINT @@bw_or_dyn; // 255 - @@bw_and_accum_var = 15; // reset to 00001111 - @@bw_and_accum_var += 85; // 00001111 & 01010101 -> 00000101 - PRINT @@bw_and_accum_var; // 5 - - // BitwiseOrAccum - @@bw_or_accum_var += 170; // 00000000 | 10101010 -> 10101010 - @@bw_or_accum_var += 85; // 10101010 | 01010101 -> 11111111 = 255 - PRINT @@bw_or_accum_var; // 255 - - @@bw_or_accum_var = 15; // reset to 00001111 - @@bw_or_accum_var += 85; // 00001111 | 01010101 -> 01011111 = 95 - PRINT @@bw_or_accum_var; // 95 -} \ No newline at end of file + // @@bw_or_dyn.resize(len + 1); // Not supported +} diff --git a/modules/appendix/examples/minimal_net/accum_bitwise_results.json b/modules/appendix/examples/minimal_net/accum_bitwise_results.json index 12725dfd..40835bfb 100644 --- a/modules/appendix/examples/minimal_net/accum_bitwise_results.json +++ b/modules/appendix/examples/minimal_net/accum_bitwise_results.json @@ -7,9 +7,8 @@ "api": "v2" }, "results": [ - {"@@bw_and_accum_var": "0000000000000000000000000000000000000000000000000000000000000000"}, - {"@@bw_and_accum_var": "0000000000000000000000000000000000000000000000000000000000000101"}, - {"@@bw_or_accum_var": "0000000000000000000000000000000000000000000000000000000011111111"}, - {"@@bw_or_accum_var": "0000000000000000000000000000000000000000000000000000000001011111"} + {"@@bw_and": "0000000000000000000000000000000000000000000000000000000000000000"}, + {"@@bw_or_long": "0000000000000000000000000000000000000000000000000000000001010101"}, + {"@@bw_or_dyn": "11111111"} ] -} \ No newline at end of file +} diff --git a/modules/appendix/examples/social_net/select_statement_index_accum_vertex_accum_edge.gsql b/modules/appendix/examples/social_net/select_statement_index_accum_vertex_accum_edge.gsql index 02416229..c844be6e 100644 --- a/modules/appendix/examples/social_net/select_statement_index_accum_vertex_accum_edge.gsql +++ b/modules/appendix/examples/social_net/select_statement_index_accum_vertex_accum_edge.gsql @@ -5,11 +5,11 @@ CREATE QUERY user_posts_2() FOR GRAPH Social_Net { start = {Person.*}; // Find all user post topics and append them to the vertex list accum - user_postings = SELECT s FROM start:s -(Posted)- :g + user_postings = SELECT s FROM (s:start) -[:Posted]- (g) ACCUM s.@person_posts += g; - user_postings = SELECT s from start:s -(Liked:e)- :g + user_postings = SELECT s FROM (s:start) -[e:Liked]- (g) ACCUM s.@person_liked_info += e; PRINT start; -} \ No newline at end of file +} diff --git a/modules/appendix/examples/social_net/select_statement_index_global_accum.gsql b/modules/appendix/examples/social_net/select_statement_index_global_accum.gsql index ee20f0e5..dc0235c1 100644 --- a/modules/appendix/examples/social_net/select_statement_index_global_accum.gsql +++ b/modules/appendix/examples/social_net/select_statement_index_global_accum.gsql @@ -4,8 +4,8 @@ CREATE QUERY user_posts_by_topic() FOR GRAPH Social_Net { start = {Person.*}; // Append subject and update the appearance count in the global map accum - posts = SELECT g FROM start -(Posted)- :g + posts = SELECT g FROM (:start) -[:Posted]- (g) ACCUM @@post_topic_counts += (g.subject -> 1); PRINT @@post_topic_counts; -} \ No newline at end of file +} diff --git a/modules/appendix/examples/social_net/select_statement_index_global_post_accum.gsql b/modules/appendix/examples/social_net/select_statement_index_global_post_accum.gsql index 4755cd75..be1b1dbd 100644 --- a/modules/appendix/examples/social_net/select_statement_index_global_post_accum.gsql +++ b/modules/appendix/examples/social_net/select_statement_index_global_post_accum.gsql @@ -5,7 +5,7 @@ CREATE QUERY person_gender(STRING gender) FOR GRAPH Social_Net { start = {ANY}; // Select all person vertices and check the gender attribute - friends = SELECT v FROM start:v + friends = SELECT v FROM (v:start) WHERE v.type == "Person" POST-ACCUM (v) CASE WHEN (v.gender == gender) THEN diff --git a/modules/appendix/examples/social_net/select_statement_index_having.gsql b/modules/appendix/examples/social_net/select_statement_index_having.gsql index 5797623c..4fbfa4f4 100644 --- a/modules/appendix/examples/social_net/select_statement_index_having.gsql +++ b/modules/appendix/examples/social_net/select_statement_index_having.gsql @@ -1,8 +1,8 @@ CREATE QUERY active_members (INT activity_threshold) FOR GRAPH Social_Net { SumAccum @activity_amount; start = {Person.*}; - result = SELECT v FROM start:v -(:e)- Post:tgt + result = SELECT v FROM (v:start) -[e]- (tgt:Post) ACCUM v.@activity_amount +=1 HAVING v.@activity_amount >= activity_threshold; PRINT result; -} \ No newline at end of file +} diff --git a/modules/appendix/examples/social_net/select_statement_index_having_literal.gsql b/modules/appendix/examples/social_net/select_statement_index_having_literal.gsql index 76bffdb6..54c724fb 100644 --- a/modules/appendix/examples/social_net/select_statement_index_having_literal.gsql +++ b/modules/appendix/examples/social_net/select_statement_index_having_literal.gsql @@ -4,11 +4,11 @@ CREATE QUERY print_member_activity() FOR GRAPH Social_Net start = {Person.*}; /* --- equivalent statements ----- - result = SELECT v FROM start:v -(:e)- Post:tgt + result = SELECT v FROM (v:start) -[e]- (tgt:Post) ACCUM v.@activity_amount +=1 HAVING true; */ - result = SELECT v FROM start:v -(:e)- Post:tgt + result = SELECT v FROM (v:start) -[e]- (tgt:Post) ACCUM v.@activity_amount +=1; PRINT result; diff --git a/modules/appendix/examples/social_net/select_statement_index_having_vs_where.gsql b/modules/appendix/examples/social_net/select_statement_index_having_vs_where.gsql index 10144024..24ea6bc3 100644 --- a/modules/appendix/examples/social_net/select_statement_index_having_vs_where.gsql +++ b/modules/appendix/examples/social_net/select_statement_index_having_vs_where.gsql @@ -3,11 +3,11 @@ CREATE QUERY active_male_members() FOR GRAPH Social_Net SumAccum @activity_amount; start = {Person.*}; // The two statements produce equivalent results - result1 = SELECT v FROM start:v -(:e)- Post:tgt + result1 = SELECT v FROM (v:start) -[e:]-> (tgt:Post) WHERE v.gender == "Male" ACCUM v.@activity_amount +=1; - result2 = SELECT v FROM start:v -(:e)- Post:tgt + result2 = SELECT v FROM (v:start) -[e:]-> (tgt:Post) ACCUM v.@activity_amount +=1 HAVING v.gender == "Male"; diff --git a/modules/appendix/examples/social_net/select_statement_index_multiple_edge_type_accum_compilable.gsql b/modules/appendix/examples/social_net/select_statement_index_multiple_edge_type_accum_compilable.gsql index 9c9a93e3..1458decb 100644 --- a/modules/appendix/examples/social_net/select_statement_index_multiple_edge_type_accum_compilable.gsql +++ b/modules/appendix/examples/social_net/select_statement_index_multiple_edge_type_accum_compilable.gsql @@ -2,7 +2,7 @@ CREATE QUERY multiple_edge_type_check_ex_2(VERTEX m1) FOR GRAPH Social_N ListAccum @@test_list1; all_user = {m1}; all_user = SELECT s - FROM all_user:s - ((Posted|Liked|Friend):e) - (Post|Person):t + FROM (s:all_user) -[e:Posted|Liked|Friend]- (t:Post|Person) ACCUM CASE WHEN e.type == "Liked" THEN // for Liked edges @@test_list1 += to_string(datetime_to_epoch(e.action_time)) @@ -12,4 +12,4 @@ CREATE QUERY multiple_edge_type_check_ex_2(VERTEX m1) FOR GRAPH Social_N @@test_list1 += to_string(datetime_to_epoch(t.post_time)) END; PRINT @@test_list1; -} \ No newline at end of file +} diff --git a/modules/appendix/examples/social_net/select_statement_index_multiple_edge_type_accum_error.gsql b/modules/appendix/examples/social_net/select_statement_index_multiple_edge_type_accum_error.gsql index 4b6f57b9..4b7c681d 100644 --- a/modules/appendix/examples/social_net/select_statement_index_multiple_edge_type_accum_error.gsql +++ b/modules/appendix/examples/social_net/select_statement_index_multiple_edge_type_accum_error.gsql @@ -2,10 +2,10 @@ CREATE QUERY multiple_edge_type_check_ex (VERTEX m1) FOR GRAPH Social_Ne ListAccum @@test_list_1, @@test_list_2, @@test_list_3; all_user = {m1}; all_user = SELECT s - FROM all_user:s - ((Posted|Liked|Friend):e) - (Post|Person):t + FROM (s:all_user) -[e:Posted|Liked|Friend]- (t:Post|Person) ACCUM @@test_list_1 += to_string(datetime_to_epoch(e.action_time)), @@test_list_2 += t.gender, @@test_list_3 += to_string(datetime_to_epoch(e.action_time)) + t.gender // <1> ; PRINT @@test_list_1, @@test_list_2, @@test_list_3; -} \ No newline at end of file +} diff --git a/modules/appendix/examples/social_net/select_statement_index_updating_indirect_reference_vertex.gsql b/modules/appendix/examples/social_net/select_statement_index_updating_indirect_reference_vertex.gsql index 3e1825c2..3e13a4e6 100644 --- a/modules/appendix/examples/social_net/select_statement_index_updating_indirect_reference_vertex.gsql +++ b/modules/appendix/examples/social_net/select_statement_index_updating_indirect_reference_vertex.gsql @@ -6,14 +6,14 @@ CREATE QUERY v_update_indirect_accum() FOR GRAPH Social_Net { persons = {Person.*}; // To each post, attach a list of persons who liked the post liked_posts = SELECT p - FROM persons:src -(Liked:e)- Post:p + FROM (src:persons) -[e:Liked]\-> (p:Post) ACCUM p.@posters += src; // To each person who liked a post, attach a list of everyone // who also liked one of this person's liked posts. liked_posts = SELECT src - FROM liked_posts:src + FROM (src:liked_posts) ACCUM FOREACH v IN src.@posters DO v.@fellows += src.@posters @@ -21,4 +21,4 @@ CREATE QUERY v_update_indirect_accum() FOR GRAPH Social_Net { ORDER BY src.subject; PRINT persons[persons.@fellows]; -} \ No newline at end of file +} diff --git a/modules/appendix/examples/social_net/select_statement_index_vertex_accum_example.gsql b/modules/appendix/examples/social_net/select_statement_index_vertex_accum_example.gsql index 3f01d4ab..d9058c1a 100644 --- a/modules/appendix/examples/social_net/select_statement_index_vertex_accum_example.gsql +++ b/modules/appendix/examples/social_net/select_statement_index_vertex_accum_example.gsql @@ -4,8 +4,8 @@ CREATE QUERY user_posts() FOR GRAPH Social_Net { start = {Person.*}; // Find all user post topics and append them to the vertex list accum - user_postings = SELECT s FROM start:s -(Posted)- :g + user_postings = SELECT s FROM (s:start) -[:Posted]- (g) ACCUM s.@person_posts += g.subject; PRINT user_postings; -} \ No newline at end of file +} diff --git a/modules/appendix/examples/social_net/select_statement_index_where.gsql b/modules/appendix/examples/social_net/select_statement_index_where.gsql index 2633c17b..671422d4 100644 --- a/modules/appendix/examples/social_net/select_statement_index_where.gsql +++ b/modules/appendix/examples/social_net/select_statement_index_where.gsql @@ -1,5 +1,5 @@ CREATE QUERY print_cat_posts() FOR GRAPH Social_Net { - cat_posts = SELECT v FROM Post:v // select only those post vertices + cat_posts = SELECT v FROM (v:Post) // select only those post vertices WHERE v.subject == "cats"; // which have a subset of 'cats' PRINT cat_posts; } \ No newline at end of file diff --git a/modules/appendix/examples/social_net/select_statement_index_where_and_or.gsql b/modules/appendix/examples/social_net/select_statement_index_where_and_or.gsql index 7e24bbd4..26fdec4c 100644 --- a/modules/appendix/examples/social_net/select_statement_index_where_and_or.gsql +++ b/modules/appendix/examples/social_net/select_statement_index_where_and_or.gsql @@ -5,42 +5,42 @@ CREATE QUERY find_female_members() FOR GRAPH Social_Net // are equivalent (i.e., produce the same results) all_vertices = {ANY}; # includes all posts and person - females = SELECT v FROM all_vertices:v + females = SELECT v FROM (v:all_vertices) WHERE v.type == "Person" AND v.gender != "Male"; - females = SELECT v FROM all_vertices:v + females = SELECT v FROM (v:all_vertices) WHERE v.type == "Person" AND v.gender == "Female"; - females = SELECT v FROM all_vertices:v + females = SELECT v FROM (v:all_vertices) WHERE v.type == "Person" AND NOT v.gender == "Male"; - females = SELECT v FROM all_vertices:v + females = SELECT v FROM (v:all_vertices) WHERE v.type != "Post" AND NOT v.gender == "Male"; /* does not compile. cannot use NOT operator in combination with type attribute - females = SELECT v FROM all_vertices:v - WHERE NOT v.type != "Person" AND - NOT v.gender == "Male"; + females = SELECT v FROM (v:all_vertices) + WHERE NOT v.type != "Person" AND + NOT v.gender == "Male"; does not compile. cannot use NOT operator in combination with type attribute - females = SELECT v FROM all_vertices:v - WHERE NOT v.type == "Post" AND - NOT v.gender == "Male"; */ + females = SELECT v FROM (v:all_vertices) + WHERE NOT v.type == "Post" AND + NOT v.gender == "Male"; person_vertices = {Person.*}; - females = SELECT v FROM person_vertices:v - WHERE NOT v.gender == "Male"; + females = SELECT v FROM (person_vertices:v) + WHERE NOT v.gender == "Male"; - females = SELECT v FROM person_vertices:v - WHERE v.gender != "Male"; + females = SELECT v FROM (person_vertices:v) + WHERE v.gender != "Male"; - females = SELECT v FROM person_vertices:v - WHERE v.gender != "Male" AND true; + females = SELECT v FROM (person_vertices:v) + WHERE v.gender != "Male" AND true; - females = SELECT v FROM person_vertices:v - WHERE v.gender != "Male" OR false; + females = SELECT v FROM (person_vertices:v) + WHERE v.gender != "Male" OR false; PRINT females; -} \ No newline at end of file +} diff --git a/modules/appendix/examples/social_net/select_statement_index_where_multiple_edge_type.gsql b/modules/appendix/examples/social_net/select_statement_index_where_multiple_edge_type.gsql index b7604809..c289f85b 100644 --- a/modules/appendix/examples/social_net/select_statement_index_where_multiple_edge_type.gsql +++ b/modules/appendix/examples/social_net/select_statement_index_where_multiple_edge_type.gsql @@ -1,7 +1,7 @@ CREATE QUERY multiple_edge_type_where_ex(VERTEX m1) FOR GRAPH Social_Net { all_user = {m1}; filtered_user = SELECT s - FROM all_user:s - ((Posted|Liked|Friend):e) - (Post|Person):t + FROM (s:all_user) -[e:Posted|Liked|Friend]-> (t:Post|Person) // WHERE e.action_time > epoch_to_datetime(1) AND t.gender == "Male"; WHERE ( e.type == "Liked" AND e.action_time > epoch_to_datetime(1) ) OR ( e.type == "Friend" AND t.gender == "Male" ); diff --git a/modules/appendix/examples/social_net/select_statement_index_where_using_in.gsql b/modules/appendix/examples/social_net/select_statement_index_where_using_in.gsql index 62ee124d..a213ee71 100644 --- a/modules/appendix/examples/social_net/select_statement_index_where_using_in.gsql +++ b/modules/appendix/examples/social_net/select_statement_index_where_using_in.gsql @@ -1,5 +1,5 @@ CREATE QUERY find_graph_focused_posts() FOR GRAPH Social_Net { - results = SELECT v FROM Post:v // select only post vertices - WHERE v.subject IN ("Graph", "tigergraph"); // which have a subject of either 'Graph' or 'tigergraph' - PRINT results; + results = SELECT v FROM (v:Post) // select only post vertices + WHERE v.subject IN ("Graph", "tigergraph"); // which have a subject of either 'Graph' or 'tigergraph' + PRINT results; } \ No newline at end of file diff --git a/modules/appendix/examples/work_net/declaration_file_object_query.gsql b/modules/appendix/examples/work_net/declaration_file_object_query.gsql index 4eb169d4..e7d6ff29 100644 --- a/modules/appendix/examples/work_net/declaration_file_object_query.gsql +++ b/modules/appendix/examples/work_net/declaration_file_object_query.gsql @@ -1,17 +1,19 @@ CREATE QUERY get_US_worker_interests (STRING file_location) FOR GRAPH Work_Net { - // Declare FILE object f1 - FILE f1 (file_location); + // Declare FILE object f1 with an octal-encoded file permission "764" + FILE f1 (file_location, "764"); + // Initialize a seed set of all person vertices P = {Person.*}; PRINT "header" TO_CSV f1; - // Select workers located in the US and print their interests onto - // the FILE object + // Select workers located in the US and print their interests onto the FILE object US_workers = SELECT v FROM P:v WHERE v.location_id == "us" ACCUM f1.println(v.id, v.interest_list); + PRINT "footer" TO_CSV f1; } + INSTALL QUERY get_US_worker_interests RUN QUERY get_US_worker_interests("/home/tigergraph/fileEx.txt") \ No newline at end of file diff --git a/modules/appendix/examples/work_net/output_statements_file_object_query_example.gsql b/modules/appendix/examples/work_net/output_statements_file_object_query_example.gsql index 9baff167..284426c6 100644 --- a/modules/appendix/examples/work_net/output_statements_file_object_query_example.gsql +++ b/modules/appendix/examples/work_net/output_statements_file_object_query_example.gsql @@ -1,13 +1,16 @@ CREATE QUERY file_ex (STRING file_location) FOR GRAPH Work_Net { - - FILE f1 (file_location); + // Declare FILE object f1 with an octal-encoded file permission "764" + FILE f1 (file_location, "764"); + + // Initialize a seed set of all person vertices P = {Person.*}; - + PRINT "header" TO_CSV f1; - + + // Select workers located in the US and print their interests USWorkers = SELECT v FROM P:v WHERE v.location_id == "us" ACCUM f1.println(v.id, v.interest_list); - + PRINT "footer" TO_CSV f1; -} \ No newline at end of file +} diff --git a/modules/appendix/examples/work_net/select_statement_index_absolute_number_edges.gsql b/modules/appendix/examples/work_net/select_statement_index_absolute_number_edges.gsql index e93cfdd0..0b2ca077 100644 --- a/modules/appendix/examples/work_net/select_statement_index_absolute_number_edges.gsql +++ b/modules/appendix/examples/work_net/select_statement_index_absolute_number_edges.gsql @@ -6,7 +6,7 @@ CREATE QUERY sample_ex_1() FOR GRAPH Work_Net { // the 'before_sample' result set encapsulates the normal functionality of // a SELECT statement, where 'times_traversed_no_sample' vertex accumulator is increased for // each edge incident to the vertex. - before_sample = SELECT v FROM workers:t -(:e)- :v + before_sample = SELECT v FROM (t:workers) -[e]- (v) ACCUM v.@times_traversed_no_sample += 1; // The 'after_sample' result set is formed by those vertices which can be @@ -14,7 +14,7 @@ CREATE QUERY sample_ex_1() FOR GRAPH Work_Net { // This is demonstrated by the values of 'times_traversed_with_sample' vertex accumulator, which // is increased for each edge incident to the vertex which is used in the // sample. - after_sample = SELECT v FROM workers:t -(:e)- :v + after_sample = SELECT v FROM (t:workers) -[e]- (v) SAMPLE 1 EDGE WHEN t.outdegree() >= 1 // only use 1 edge from the source vertex ACCUM v.@times_traversed_with_sample += 1; diff --git a/modules/appendix/examples/work_net/select_statement_index_vertex_post_accum.gsql b/modules/appendix/examples/work_net/select_statement_index_vertex_post_accum.gsql index 542db5ca..ed7ff294 100644 --- a/modules/appendix/examples/work_net/select_statement_index_vertex_post_accum.gsql +++ b/modules/appendix/examples/work_net/select_statement_index_vertex_post_accum.gsql @@ -6,7 +6,7 @@ CREATE QUERY resident_employees() FOR GRAPH Work_Net { start = {Person.*}; - employees = SELECT s FROM start:s -(Works_For)- :c + employees = SELECT s FROM (s:start) -[:Works_For]- (c) // If a person works for a company in the same country where they live, add the company to the list ACCUM CASE WHEN (s.location_id == c.country) THEN @@ -22,4 +22,4 @@ CREATE QUERY resident_employees() FOR GRAPH Work_Net { END; PRINT employees WHERE (employees.@works_and_lives == TRUE); -} \ No newline at end of file +} diff --git a/modules/appendix/examples/work_net/select_statement_index_where_using_edge_attributes.gsql b/modules/appendix/examples/work_net/select_statement_index_where_using_edge_attributes.gsql index d868a7dc..52c8583b 100644 --- a/modules/appendix/examples/work_net/select_statement_index_where_using_edge_attributes.gsql +++ b/modules/appendix/examples/work_net/select_statement_index_where_using_edge_attributes.gsql @@ -1,7 +1,7 @@ CREATE QUERY full_time_workers() FOR GRAPH Work_Net { // find all workers who are full time at some company start = {Person.*}; - full_time_workers = SELECT v FROM start:v -(Works_For:e)- Company:t + full_time_workers = SELECT v FROM (v:start) -[e:Works_For]- (t:Company) WHERE e.full_time; // full_time is a boolean attribute on the edge PRINT full_time_workers; diff --git a/modules/appendix/nav.adoc b/modules/appendix/nav.adoc index 54d22223..2528f160 100644 --- a/modules/appendix/nav.adoc +++ b/modules/appendix/nav.adoc @@ -1,12 +1,12 @@ * Appendix +** xref:common-errors-and-problems.adoc[] +** xref:keywords-and-reserved-words.adoc[DLL Keywords & Reserved Words] +** xref:notations.adoc[Documentation Notation] +** xref:example-graphs.adoc[] +** xref:cheat-sheets.adoc[GSQL Cheat Sheets] +** xref:gsql-start-to-end-process.adoc[] ** xref:gsql-style-guide.adoc[] -** xref:keywords-and-reserved-words.adoc[] -** xref:query-language-reserved-words.adoc[] //** xref:complete-formal-syntax.adoc[] ** xref:interpreted-gsql-limitations.adoc[] -** xref:gsql-start-to-end-process.adoc[] -** xref:example-graphs.adoc[] -** xref:common-errors-and-problems.adoc[] -** xref:cheat-sheets.adoc[] -** xref:notations.adoc[] -* xref:appendix:legacy-tg-versions.adoc[] \ No newline at end of file +** xref:legacy-tg-versions.adoc[] +** xref:query-language-reserved-words.adoc[] \ No newline at end of file diff --git a/modules/appendix/pages/common-errors-and-problems.adoc b/modules/appendix/pages/common-errors-and-problems.adoc index b513441a..15095f6f 100644 --- a/modules/appendix/pages/common-errors-and-problems.adoc +++ b/modules/appendix/pages/common-errors-and-problems.adoc @@ -7,6 +7,7 @@ No computer can store all floating point numbers (i.e., non-integers) with perfe The `FLOAT` data type offers about 7 decimal digits of precision; the `DOUBLE` data type offers about 15 decimal digits of precision. These are the same precision limits as in C++. +=== Exact comparison of floating point numbers is not appropriate Comparing two float or double values by using operators involving exact equality (`==`, `+<=+`, `>=`, `BETWEEN ... AND ...`) might lead to unexpected behavior. If the GSQL language parser detects that the user is attempting an exact equivalence test with float or double data types, it will display a warning message and suggestion. @@ -21,6 +22,23 @@ comparison with an error margin, e.g. 'abs((v) - (v2)) < epsilon', where epsilon is a very small positive value of your choice, such as 0.0001. ---- +=== Adding floating point values at different scales is problematic + +When two addends are at different scales, the sum may call for more precision than is available. Imagine you have two `FLOAT` variables: + +[console] +---- +A = 1234567. +B = 0.1234567 +---- + +What is `A + B`? +In pure math, the answer is `1234567.1234567`. +But that requires 14 digits of precision, while `FLOAT` offers only about 7 digits. +This problem can occur inadvertently when adding a large set of numbers. +The individual numbers may be about the same scale, but the intermediate sums are of a larger scale. + + == Response to Non-existent vertex ID If a query has a vertex parameter (`VERTEX` or `VERTEX`), and if the ID for a nonexistent vertex is given when running the query, an error message is shown, and the query won't run. This is also the response when calling a function to convert a single vertex ID string to a vertex: diff --git a/modules/appendix/pages/keywords-and-reserved-words.adoc b/modules/appendix/pages/keywords-and-reserved-words.adoc index 1126808a..c674975d 100644 --- a/modules/appendix/pages/keywords-and-reserved-words.adoc +++ b/modules/appendix/pages/keywords-and-reserved-words.adoc @@ -89,7 +89,6 @@ The compiler will reject the use of a reserved word as well as any word beginnin * FOR * FOREACH * FROM -* FUNCTION * GLOBAL * GRANTS * GRAPH @@ -237,6 +236,7 @@ These keywords in the language are non-reserved, so users may use them for user- * FILENAME * FLATTEN * FLATTEN_JSON_ARRAY +* FUNCTION * GEN-DATA * GET * GRANT diff --git a/modules/appendix/pages/legacy-tg-versions.adoc b/modules/appendix/pages/legacy-tg-versions.adoc index fe5bc250..ba4dcf2e 100644 --- a/modules/appendix/pages/legacy-tg-versions.adoc +++ b/modules/appendix/pages/legacy-tg-versions.adoc @@ -4,10 +4,8 @@ This page lists all LTS (Long-Term Support) and previous versions of GSQL. == LTS Versions - * xref:3.10@gsql-ref:intro:index.adoc[3.10] -* xref:3.9@gsql-ref:intro:index.adoc[3.9] -* xref:3.6@gsql-ref:intro:intro.adoc[3.6] + == Other Versions diff --git a/modules/basics/nav.adoc b/modules/basics/nav.adoc index ea890cfe..cbe42cc0 100644 --- a/modules/basics/nav.adoc +++ b/modules/basics/nav.adoc @@ -1 +1 @@ -* xref:system-and-language-basics.adoc[] \ No newline at end of file +* xref:running-gsql.adoc[] \ No newline at end of file diff --git a/modules/basics/pages/system-and-language-basics.adoc b/modules/basics/pages/running-gsql.adoc similarity index 96% rename from modules/basics/pages/system-and-language-basics.adoc rename to modules/basics/pages/running-gsql.adoc index 25d6eabd..72ddfabb 100644 --- a/modules/basics/pages/system-and-language-basics.adoc +++ b/modules/basics/pages/running-gsql.adoc @@ -1,6 +1,7 @@ -= System & Language Basics += Running GSQL :pp: {plus}{plus} -:page-aliases: ddl-and-loading:system-and-language-basics.adoc +:page-aliases: ddl-and-loading:system-and-language-basics.adoc, system-and-language-basics.adoc +:description: GSQL system and language basic concepts. How to run GSQL. This page describes the basic elements that make up the GSQL Data Definition and Loading as well as the GSQL Query Language. It also provides instructions on how to run GSQL commands through the GSQL shell, including the new token-based authentication functionality added in version 4.1. @@ -29,7 +30,7 @@ Some punctuation may be needed to separate the statements within a block. Single-line comments begin with either `#` or `//`. A comment may be on the same line as interpreted code. Text to the left of the comment marker is interpreted, and text to the right of the marker is ignored. -Multi-line comment blocks begin with `/*` and end with `*/`. +Multi-line comment blocks begin with `/\*` and end with `*/`. == Running GSQL @@ -81,7 +82,7 @@ gsql -t *Types of tokens* * *Plain-text Token:* A randomly generated string used for authentication. This is the older token format, still supported if not expired, but will eventually be deprecated. -* **xref:4.1@tigergraph-server:user-access:jwt-token.adoc#_usage_of_gsql_jwt_token[JWT Token]**: A more secure and modern format for authentication. It consists of three parts: header, payload, and signature. JWT tokens are the default format for authentication starting from version 4.1. +* **xref:{page-component-version}@tigergraph-server:user-access:jwt-token.adoc#_usage_of_gsql_jwt_token[JWT Token]**: A more secure and modern format for authentication. It consists of three parts: header, payload, and signature. JWT tokens are the default format for authentication starting from version 4.1. *Token login workflow* diff --git a/modules/ddl-and-loading/nav.adoc b/modules/ddl-and-loading/nav.adoc index 92dbc3f9..fbf56634 100644 --- a/modules/ddl-and-loading/nav.adoc +++ b/modules/ddl-and-loading/nav.adoc @@ -1,10 +1,11 @@ -* xref:attribute-data-types.adoc[] -* xref:index.adoc[Schema Definition] + +* xref:index.adoc[Defining a Schema] +** xref:attribute-data-types.adoc[Data Types] ** xref:defining-a-graph-schema.adoc[Define a Graph Schema] ** xref:modifying-a-graph-schema.adoc[Modify a Graph Schema] -* xref:loading-jobs.adoc[Loading Jobs] +* xref:loading-jobs.adoc[Loading Data] ** xref:creating-a-loading-job.adoc[Create a Loading Job] *** xref:functions/index.adoc[] **** xref:functions/token/index.adoc[] @@ -30,6 +31,8 @@ ***** xref:functions/token/gsql_to_uint.adoc[] ***** xref:functions/token/gsql_trim.adoc[] ***** xref:functions/token/gsql_ts_to_epoch.adoc[] +***** xref:functions/token/gsql_ts_to_epoch_legacy.adoc[] +***** xref:functions/token/gsql_ts_to_epoch_signed.adoc[] ***** xref:functions/token/gsql_upper.adoc[] ***** xref:functions/token/gsql_uuid_v4.adoc[] ***** xref:functions/token/gsql_year.adoc[] @@ -38,7 +41,7 @@ **** xref:functions/token_where/index.adoc[] ***** xref:functions/token_where/concat.adoc[] ***** xref:functions/token_where/gsql_is_false.adoc[] -***** xref:functions/token_where/gsql_is_not_empty.adoc[] +***** xref:functions/token_where/gsql_is_not_empty_string.adoc[] ***** xref:functions/token_where/gsql_is_true.adoc[] ***** xref:functions/token_where/gsql_token_equal.adoc[] ***** xref:functions/token_where/gsql_token_ignore_case_equal.adoc[] @@ -54,4 +57,4 @@ ***** xref:functions/reducer/or.adoc[] *** xref:add-token-function.adoc[] ** xref:running-a-loading-job.adoc[Run a Loading Job] -** xref:managing-loading-job.adoc[Manage Loading Jobs] \ No newline at end of file +** xref:managing-loading-job.adoc[Manage Loading Jobs] diff --git a/modules/ddl-and-loading/pages/add-token-function.adoc b/modules/ddl-and-loading/pages/add-token-function.adoc index 267985e2..972e7e1a 100644 --- a/modules/ddl-and-loading/pages/add-token-function.adoc +++ b/modules/ddl-and-loading/pages/add-token-function.adoc @@ -134,7 +134,6 @@ If GitHub access is configured, GSQL will retrieve user source code files from G TigerGraph only allows one TokenBank file at a time. Files on GitHub take priority. If GitHub is connected but files are missing, TigerGraph will look for a TokenBank file added via `PUT`. -New additions to the files in the GitHub repository are instantly available in GSQL. You can retrieve the TokenBank from `AppRoot/dev/gdk/gsql/src/TokenBank/TokenBank.cpp` and copy it to a Git repository of your choice. @@ -153,9 +152,20 @@ The `gadmin` configuration parameters for setting up the connection to GitHub ar | `GSQL.GithubBranch` | The branch to access | `main` | `GSQL.GithubPath` | Path to the directory in the repository that has `TokenBank.cpp` | `src/` | `GSQL.GithubUrl` | Optional parameter used for GitHub Enterprise | `https://api.github.com` +| `GSQL.GithubEnabled` | To Enable the retrieval of UDFs (such as ExprFunctions.hpp, ExprUtils.hpp, etc.) from GitHub (default `false`). | `false` |=== + +[NOTE] +==== +When upgrading the database from a version where the parameter `GSQL.GithubEnabled` did not exist (pre 4.1.3) to one where it does, the upgrade process will set `GSQL.GithubEnabled` to `true`. +==== -Use the xref:tigergraph-server:system-management:management-with-gadmin.adoc#_gadmin_config_set[`gadmin config set`] command to configure the aforementioned parameters to connect GSQL to the GitHub repository hosting your files. +Use the xref:{page-component-version}@tigergraph-server:system-management:management-commands.adoc#_gadmin_config_set[`gadmin config set ` command] to configure the aforementioned parameters to connect GSQL to the GitHub repository hosting your files. + +[TIP] +==== +Run `gadmin config get ` to find out the current setting of a parameter. +==== Below is an example configuration. Remember to run `gadmin config apply` after changing the parameters. If GSQL is already running, you will need to run `gadmin restart all` to restart GSQL before the token functions become available. @@ -171,10 +181,19 @@ gadmin config apply After the parameters are successfully configured, you can access your user-defined token functions right away. +=== Update UDFs sourced from GitHub + +Prior to 4.1, each time GSQL was run, it would check to see if the UDF files on GitHub had changed. +If they had, it would download the new files and install them. + +Beginning in 4.1, GSQL only checks GitHub if more than one hour has elapsed since the last check. + +To force GSQL to install new UDF files from GitHub, run `gadmin restart all` to restart GSQL. + == Store token functions locally All UDF files are scanned by the system to ensure that they comply with the UDF file policy as set by configuration commands in TigerGraph Server. -For more details, see xref:tigergraph-server:security:index.adoc[TigerGraph Server - Security]. +For more details, see xref:{page-component-version}@tigergraph-server:security:index.adoc[TigerGraph Server - Security]. === Step 1: Enable adding a TokenBank with PUT @@ -239,4 +258,4 @@ For best security practices, run the following commands to once more disable upl $ gadmin config set GSQL.UDF.EnablePutTokenBank false $ gadmin config apply $ gadmin restart gsql ----- \ No newline at end of file +---- diff --git a/modules/ddl-and-loading/pages/attribute-data-types.adoc b/modules/ddl-and-loading/pages/attribute-data-types.adoc index fc7264b2..9a5856a5 100644 --- a/modules/ddl-and-loading/pages/attribute-data-types.adoc +++ b/modules/ddl-and-loading/pages/attribute-data-types.adoc @@ -12,38 +12,50 @@ This page describes the different data types that can be stored in vertex and ed Primitive types are the most basic data types available within GSQL. They can also be used to construct other complex data types. - +[%autowidth] |=== | Name | Default value | Valid input format (regex) | Range and precision | Description | `INT` | 0 | [-+]?[0-9]+ -| --2{caret}63 to +2{caret}63 - 1 (-9,223,372,036,854,775,808 to 9,223,372,036,854,775,807) +| -2^63^ to +2^63^ - 1 +(-9,223,372,036,854,775,808 to 9,223,372,036,854,775,807) | 8-byte signed integer | `UINT` | 0 | [0-9]+ -| 0 to 2{caret}64 - 1 (18,446,744,073,709,551,615) +| 0 to 2^64^ - 1 + +(0 to 18,446,744,073,709,551,615) | 8-byte unsigned integer | `FLOAT` | 0.0 -| [ -+ ] ? [ 0 - 9 ] * . ? [ 0 - 9 ] +( [ eE ] [ -+ ] ? [ 0 - 9 ] + ) ? -| +/- 3.4 E +/-38, ~7 decimal digits of precision. -| 4-byte single-precision floating point number Examples: 3.14159, .0065e14, 7E23 See note below. +| [ -+ ]? [ 0 - 9 ]* .? [ 0 - 9 ] + +( [ eE ] [ -+ ]? [ 0 - 9 ]+ )? +| +/- 3.4 E +/-38, + +~7 decimal digits of precision. +a| 4-byte single-precision floating point number Examples: 3.14159, .0065e14, 7E23. *See notes below*. + | `DOUBLE` | 0.0 -| [ -+ ] ? [ 0 - 9 ] * . ? [ 0 - 9 ] +( [ eE ] [ -+ ] ? [ 0 - 9 ] + ) ? -| +/- 1.7 E +/-308, ~16 decimal digits of precision +| [ -+ ]? [ 0 - 9 ]* .? [ 0 - 9 ] + +( [ eE ] [ -+ ]? [ 0 - 9 ] + )? +| +/- 1.7 E +/-308, + +~16 decimal digits of precision | 8-byte double-precision floating point number. -Has the same input and output format as FLOAT, but the range and precision are greater. See note below. +Has the same input and output format as FLOAT, but the range and precision are greater. *See notes below*. | `BOOL` -| false -| true, false (case insensitive), 1, 0 -| true, false +| `false` +| `true`, `false` (case insensitive), 1, 0 +| `true`, `false` | Boolean true and false, represented within GSQL as _true_ and _false_ , and represented in input and output as 1 and 0 | `STRING` @@ -57,6 +69,15 @@ The string value can optionally be enclosed by single quote marks or double quot |=== [NOTE] +.FLOAT and DOUBLE +==== +Remember that FLOAT and DOUBLE have limited precision. +In particular, for large numbers that require precision, `DOUBLE` is the better choice. +==== + + +[NOTE] +.Display format ==== [For v3.9.2+] FLOAT and DOUBLE values are displayed with up to 7 and 16 digits of precision, respectively. ==== diff --git a/modules/ddl-and-loading/pages/creating-a-loading-job.adoc b/modules/ddl-and-loading/pages/creating-a-loading-job.adoc index de17dc79..df3cce38 100644 --- a/modules/ddl-and-loading/pages/creating-a-loading-job.adoc +++ b/modules/ddl-and-loading/pages/creating-a-loading-job.adoc @@ -32,7 +32,7 @@ Either pre-process your data files to remove extra spaces, or use GSQL's token p [NOTE] User privileges for running loading jobs are treated as separate from privileges regarding reading and writing data to vertices and edges. A user can create and run loading jobs even without the privileges to modify vertex and edge data. -For more information, see xref:tigergraph-server:user-access:access-control-model.adoc[]. +For more information, see xref:{page-component-version}@tigergraph-server:user-access:access-control-model.adoc[]. == Loading job capabilities @@ -52,7 +52,7 @@ Furthermore, if the TigerGraph graph is distributed (partitioned) across multipl [NOTE] To maximize loading performance in a cluster, use at least two loaders per machine, and assign each loader approximately the same amount of data. -A concurrent-capable loading job can logically be separated into parts according to each file variable. When a concurrent-capable loading job is compiled, a xref:tigergraph-server:API:built-in-endpoints.adoc#_run_a_loading_job[RESTPP endpoint] is generated for the loading job, which you can call to load data into your graph as an alternative to `RUN LOADING JOB`. +A concurrent-capable loading job can logically be separated into parts according to each file variable. When a concurrent-capable loading job is compiled, a xref:{page-component-version}@tigergraph-server:API:built-in-endpoints.adoc#_run_a_loading_job[RESTPP endpoint] is generated for the loading job, which you can call to load data into your graph as an alternative to `RUN LOADING JOB`. [NOTE] ==== @@ -158,7 +158,7 @@ There are four options for `filepath_string`: If it is a folder, then the loader will attempt to load each non-hidden file in the folder. If this path is not valid when `CREATE LOADING JOB` is executed, GSQL will report an error. + -An absolute path may begin with the xref:tigergraph-server:gsql-shell:gsql-sessions.adoc[session parameter] `$sys.data_root`. +An absolute path may begin with the xref:{page-component-version}@tigergraph-server:gsql-shell:gsql-sessions.adoc[session parameter] `$sys.data_root`. * An absolute or relative path for either a file or a folder *on all machines in the cluster*: If the path is prefixed with `all:`, then the loading job will attempt to run on every machine in the cluster which has a RESTPP component, and each machine will look locally for data at _path_. *If the path is invalid on any of the machines, the job will be aborted*. Also, the session parameter `$sys.data_root` may not be used. + .`ALL:path` examples @@ -200,7 +200,7 @@ DEFINE HEADER header_name = " column_name "[," column_name "]*; === `DEFINE INPUT_LINE_FILTER` -NOTE: This statement is not supported in a xref:tigergraph-server:data-loading:kafka-loader/index.adoc[Kafka loading job]. +NOTE: This statement is not supported in a xref:{page-component-version}@tigergraph-server:data-loading:kafka-loader/index.adoc[Kafka loading job]. The `DEFINE INPUT_LINE_FILTER` statement defines a named Boolean expression whose value depends on column attributes from a row of input data. When combined with a `USING reject_line_rule` clause in a `LOAD` statement, the filter determines whether an input line is ignored or not. @@ -330,7 +330,7 @@ In both cases, the leading sign ("+" or "-") is optional. The exponent, using "e === Loading a `DATETIME` attribute -When loading data into a `DATETIME` attribute, the GSQL loader automatically reads a string representation of DateTime information and convert it to internal DateTime representation. +When loading data into a `DATETIME` attribute, the GSQL loader automatically reads a string representation of DateTime information and converts it to an internal DateTime representation. The loader accepts any of the following string formats: * `%Y-%m-%d %H:%M:%S` (e.g., 2011-02-03 01:02:03) @@ -338,13 +338,13 @@ The loader accepts any of the following string formats: * `%Y-%m-%dT%H:%M:%S.000z` (e.g., 2011-02-03T01:02:03.123z, 123 will be ignored) * `%Y-%m-%d` (only date, no time, e.g., 2011-02-03) * `%Y/%m/%d` (only date, no time, e.g., 2011/02/03) -* Any integer value (Unix Epoch time, where Jan 1, 1970 at 00:00:00 is integer 0) +* A Unix Epoch timestamp represented as a string (e.g., `"0"` represents Jan 1, 1970 at 00:00:00 UTC) Format notation: %Y is a 4-digit year. A 2-digit year is not a valid value. -%m and %s are a month (1 to 12) and a day (1 to 31), respectively. Leading zeroes are optional. +%m and %d are a month (1 to 12) and a day (1 to 31), respectively. Leading zeroes are optional. %H, %M, %S are hours (0 to 23), minutes (0 to 59) and seconds (0 to 59), respectively. Leading zeroes are optional. @@ -618,7 +618,7 @@ Token functions are functions in the DDL language that operate on tokens.Some ma To use a token function, replace the attribute in the destination clause of the `LOAD` statement with the function call.The arguments of the function can be a column from the `FILE` object. [discrete] -==== Example +=== Example: [source,gsql] ---- diff --git a/modules/ddl-and-loading/pages/defining-a-graph-schema.adoc b/modules/ddl-and-loading/pages/defining-a-graph-schema.adoc index d38408e7..e5e73526 100644 --- a/modules/ddl-and-loading/pages/defining-a-graph-schema.adoc +++ b/modules/ddl-and-loading/pages/defining-a-graph-schema.adoc @@ -17,7 +17,7 @@ For example, it does not specify whether a User may connect to multiple occupati .A schema for a User-Book-Rating graph image::user-book-rating-schema.png[A schema for a User-Book-Rating graph. The vertex User is connected to Occupation with the user_occupation edge and to Book with the user_book_rating edge. Book is connected to Genre with the book_genre edge.] -An edge connects two vertices: a _source vertex_ and a _target vertex_ . +An edge connects two vertices: a _source vertex_ and a _target vertex_. An edge type can be either _directed_ or _undirected_. A directed edge has a clear semantic direction, from the source vertex to the target vertex. For example, if there is an edge type that represents a plane flight segment, each segment needs to distinguish which airport is the origin (source vertex) and which airport is the destination (target vertex). @@ -53,10 +53,58 @@ Once the graph designer has chosen a graph schema, the schema is ready to be for ==== You need the `WRITE_SCHEMA` privilege in the scope you are operating on to run commands that alter the graph schema. -To learn more about permission and privileges, see xref:tigergraph-server:user-access:access-control-model.adoc[]. +To learn more about permission and privileges, see xref:{page-component-version}@tigergraph-server:user-access:access-control-model.adoc[]. ==== -== `CREATE VERTEX` +== Global and Local Schemas + +In GSQL schema terminology, a *_graph_* is a subset of the database's vertex types and related edge types. That is, it is a subschema of the graph's total (global) schema. +(See xref:{page-component-version}@tigergraph-server:intro:multigraph-overview.adoc[]). + +Each graph is an access domain; users are granted the privilege to work on a particular graph(s). +We use *_local_* to mean graph-level as opposed to global level. + +Each vertex type or edge type is created as either global or local. + +A global type: + +* Can only be created or modified by a user with global schema prilivege, using xref:_create_vertex[] and xref:_create_edge[]. ++ +NOTE: Run xref:modifying-a-graph-schema.adoc#_use_global[USE GLOBAL] first to enter global mode. + +* Is put to use by assigning it to one or more local graph schemas, with xref:_create_graph[] or xref:modifying-a-graph-schema.adoc#_create_global_schema_change_job[GLOBAL SCHEMA CHANGE]. This means it is shared: any change to a global vertex is seen by all graphs that have that vertex. +* Queries run only on (local) graphs, not on the global schema. + +A local type: + +* Can only be created or modified by a user with schema privilege for that particular graph, using a xref:modifying-a-graph-schema.adoc[(local) SCHEMA CHANGE JOB] (not with CREATE VERTEX/EDGE). +* Is visible only to users with read privilege on that graph. + +Hence, a local graph can be a combination of global (shared) and local element types. + +Suppose we have Book and User vertex types which are both global. The friend_of and user_book_rating edges are local, belonging to the Rating_graph and Social_graph, respectively. +The bracketed numbers refer on one possible sequence for how the database got to this state. + +[cols="<,^,^,^"] +|=== +| type | scope |Rating_graph <3>| Social_graph <5> + +| Book <1> | global | x <3> | x <7> +| User <2> | global | x <3> | x <5> +| user_book_rating <4> | local | x <4> | +| friend_of <6> | local | | x <6> +|=== + +1. Book was created with CREATE VERTEX. +2. User was created with CREATE VERTEX. +3. Rating_graph was created with CREATE GRAPH, containing Book and User vertices. +4. user_book_rating was created with a SCHEMA CHANGE JOB on Rating_graph. +5. Social_graph was created with CREATE GRAPH, containing only User vertices. +6. friend_of was created with a SCHEMA CHANGE JOB on Social_graph. +7. Book was added to Social_graph using a GLOBAL SCHEMA CHANGE JOB. + + +== CREATE VERTEX *Required privilege*: `WRITE_SCHEMA` @@ -104,8 +152,9 @@ attribute_list := ["," attribute_name type [DEFAULT default_value] ]* ---- -`id_type` may be `STRING`, `INT`, `UINT`, or `DATETIME`. -Once a vertex is inserted, its ID value cannot be modified. Every vertex must have a unique ID value, of course. +`id_type` may be `STRING`, `INT`, or `UINT`. +`DATETIME` is *not supported* as a primary ID type. +Once a vertex is inserted, its ID value cannot be modified. Every vertex must have a unique ID value. [IMPORTANT] An empty string is not a valid value for a vertex primary ID. Beginning with v3.9, GSQL will reject attempts to insert or load a vertex whose ID is an empty string. @@ -120,8 +169,10 @@ The following sections go into detail for each of the primary id/key options, at === PRIMARY_ID This is GSQL's original syntax and semantics. -Its data type may be `STRING`, `INT`, `UINT`, or `DATETIME`. -Its syntax for the `id_and_attribute_list` term is as follows: +Its data type may be `STRING`, `INT`, or `UINT`. +`DATETIME` is *not supported* as a primary ID type. + +The syntax for the `id_and_attribute_list` term is as follows: PRIMARY_ID id_name id_type "," attribute_list @@ -129,10 +180,10 @@ Example: [source.wrap,ebnf] ---- -CREATE VERTEX Movie (id UINT PRIMARY KEY, name STRING, year UINT) +CREATE VERTEX Movie (PRIMARY_ID id UINT, name STRING, year UINT) ---- -By default, a vertex type which is defined with `PRIMARY_ID` cannot treat the ID as a regular attribute. For example, if the ID's field name is `serial_num`, neither of the following syntaxes are valid: +By default, a vertex type defined with `PRIMARY_ID` cannot treat the ID as a regular attribute. For example, if the ID's field name is `serial_num`, neither of the following syntaxes are valid: [source.wrap] ---- @@ -140,11 +191,12 @@ By default, a vertex type which is defined with `PRIMARY_ID` cannot treat the ID v.id // error: id is not a built-in function or field name ---- -If you want to retreive a vertex having a specific ID, you can use the `to_vertex(id, type)` function. +To retrieve a vertex by its ID, use the `to_vertex(id, type)` function. -See the next section to see how to override the default behavior and treat the primary ID as attribute. +See the next section for how to override the default behavior and treat the primary ID as an attribute. === `WITH primary_id_as_attribute` + If the `WITH ... primary_id_as_attribute="true"` option is declared, then the ID can be treated as a readable attribute. Internally, the ID is being stored a second time, once as an ID and once as a write-once attribute. This is exactly the same way that PRIMARY KEY allows the ID to be treated as a vertex. @@ -274,7 +326,7 @@ image::comms-graph-outdegree.png["Diagram of a graph with five person vertices. | 1 |=== -== `CREATE EDGE` +== CREATE EDGE `CREATE EDGE` defines a new global edge type. Data loaded to a global edge type in one graph will be shared across all graphs that use that edge type. See xref:modifying-a-graph-schema.adoc#_global_vs_local_schema_changes[Global vs. local schema changes] for instructions on creating local edges. @@ -420,7 +472,7 @@ User-defined types at the catalog level can only be used for query return value Once defined, all graphs in the database have access to these user-defined types, and subqueries can be defined to return the user-defined types. [discrete] -==== Example: +=== Example: The example below defines a tuple type `My_Tuple` and a heap accumulator type `My_Heap`, so that the subquery `Sub_Query_1` can return a value of `My_Heap` type to its outer query `Query_1`. @@ -463,7 +515,7 @@ Example: `ALTER VERTEX User ADD INDEX user_country_index ON (country);` -== `CREATE GRAPH` +== CREATE GRAPH `CREATE GRAPH` defines a graph schema, which contains the given vertex types and edge types, and prepares the graph store to accept data. The vertex types and edge types may be listed in any order. @@ -561,7 +613,7 @@ New requirement for MultiGraph support. Applies even if only one graph exists. Before a user can use a graph, the user must be granted a role on that graph by an admin user of that graph or by a superuser. (Superusers are automatically granted the admin role on every graph). Second, for each GSQL session, the user must set a working graph. The `USE GRAPH` command sets or changes the user's working graph, for the current session. -For more about roles and privileges, see the document xref:tigergraph-server:user-access:index.adoc[Managing User Privileges and Authentication]. +For more about roles and privileges, see the document xref:{page-component-version}@tigergraph-server:user-access:index.adoc[Managing User Privileges and Authentication]. .USE GRAPH syntax [source,gsql] @@ -590,9 +642,9 @@ The `DROP GRAPH` command deletes the logical definition of the named graph. It w === Required privilege `Drop_ALL` -The `DROP ALL` command clears the graph store (i.e. deletes all data) and removes all definitions from the catalog: vertex types, edge types, graph types, jobs, and queries. +The `DROP ALL` command clears the entire graph store (i.e. deletes all data) and removes all data-related definitions from the catalog: vertex types, edge types, graph types, jobs, and queries. It will also erase graph-specific roles. -Unlike xref:tigergraph-server:getting-started:database-definition.adoc#_reset_all[the `gsql --reset` command], `DROP ALL` does not erase user and role information. +Unlike xref:{page-component-version}@tigergraph-server:getting-started:database-definition.adoc#_reset_all[the `gsql --reset` command], `DROP ALL` does not erase user and role information nor system settings. [CAUTION] ==== diff --git a/modules/ddl-and-loading/pages/functions/reducer/index.adoc b/modules/ddl-and-loading/pages/functions/reducer/index.adoc index 98d1523e..88e901d6 100644 --- a/modules/ddl-and-loading/pages/functions/reducer/index.adoc +++ b/modules/ddl-and-loading/pages/functions/reducer/index.adoc @@ -18,7 +18,7 @@ REDUCE(reducer_function (input_expr)) Each reducer function can be used for several data types: * For primitive data types, the output type is the same as the type of the input expression `input_expr`. -* For `LIST`, `SET`, and `MAP` containers, the `input_expr` type is one of the xref:system-and-language-basics.adoc#_collection_types[allowed element types] for these containers. +* For `LIST`, `SET`, and `MAP` containers, the `input_expr` type is one of the xref:ddl-and-loading:attribute-data-types.adoc#_collection_types[allowed element types] for these containers. The output is the entire container. == Table of reducer functions diff --git a/modules/ddl-and-loading/pages/functions/token/gsql_ts_to_epoch.adoc b/modules/ddl-and-loading/pages/functions/token/gsql_ts_to_epoch.adoc index 53906880..25500a29 100644 --- a/modules/ddl-and-loading/pages/functions/token/gsql_ts_to_epoch.adoc +++ b/modules/ddl-and-loading/pages/functions/token/gsql_ts_to_epoch.adoc @@ -1,13 +1,9 @@ = gsql_ts_to_epoch_seconds() -Converts a timestamp in canonical string format to Unix epoch time, which is the number of seconds since Jan 1st, 1970. +Converts a timestamp in canonical string format to Unix epoch time, which is the number of seconds since Jan 1, 1970 00:00. -The timestamp parameter should be in one of the following formats: - -* `"%Y-%m-%d %H:%M:%S"` -* `"%Y/%m/%d %H:%M:%S"` -* `"%Y-%m-%dT%H:%M:%S.000z"` -** Text after the dot `.` is ignored +In 4.2.1, two new timestamp conversion functions are available for loading jobs, offering different behaviors for date handling, especially for dates prior to 1970: +xref:ddl-and-loading:functions/token/gsql_ts_to_epoch_legacy.adoc[gsql_ts_to_epoch_seconds_legacy()] and xref:ddl-and-loading:functions/token/gsql_ts_to_epoch_signed.adoc[gsql_ts_to_epoch_seconds_signed()]. == Syntax `gsql_ts_to_epoch_seconds(timestamp)` @@ -16,12 +12,51 @@ The timestamp parameter should be in one of the following formats: timestamp:: Required. The timestamp to convert to Unix epoch time. +The timestamp parameter should be in one of the following formats: +* `"%Y-%m-%d %H:%M:%S"` +* `"%Y/%m/%d %H:%M:%S"` +* `"%Y-%m-%dT%H:%M:%S.000z"` +** Text after the dot `.` is ignored == Return type `UINT` +* Returns the number of seconds since `1970-01-01 00:00:00` for valid timestamps within the supported range. +* Throws an exception if the timestamp is invalid or before `1970-01-01 00:00:00`. + == Example ---- gsql_ts_to_epoch_seconds("2022-06-30 22-08-28") -> 1656652105 ----- \ No newline at end of file +---- + +:table-caption!: +.Comparison of Timestamp Conversion Functions +[%autowidth] +|=== +|Function |Return type |Supported Time Range |Response to Invalid/Unsupported Datetimes |Description + +|gsql_ts_to_epoch_seconds() +|`UINT` +|`1970-01-01 00:00:00` to `9999-12-31 23:59:59` +|Throws exception +|Converts a timestamp to Unix epoch time (from 1970 onwards). + +|gsql_ts_to_epoch_seconds_legacy() +|`uint64_t` +|`1970-01-01 00:00:00` to `9999-12-31 23:59:59` +|Returns defaultTimestamp +|Similar to `gsql_ts_to_epoch_seconds()`, but returns 0 for pre-1970 timestamps, maintaining backward compatibility. + +|gsql_ts_to_epoch_seconds_signed() +|`int64_t` +|`0001-01-01 00:00:00` to `9999-12-31 23:59:59` +|Returns defaultTimestamp +|Supports a full date range, including pre-1970 timestamps, and returns negative epoch values for those dates. + +|=== + +[TIP] +==== +If you need to avoid exceptions for invalid or pre-1970 dates, or require support for historical dates, consider using xref:ddl-and-loading:functions/token/gsql_ts_to_epoch_legacy.adoc[gsql_ts_to_epoch_seconds_legacy()] or xref:ddl-and-loading:functions/token/gsql_ts_to_epoch_signed.adoc[gsql_ts_to_epoch_seconds_signed()]. +==== diff --git a/modules/ddl-and-loading/pages/functions/token/gsql_ts_to_epoch_legacy.adoc b/modules/ddl-and-loading/pages/functions/token/gsql_ts_to_epoch_legacy.adoc new file mode 100644 index 00000000..7c6201a7 --- /dev/null +++ b/modules/ddl-and-loading/pages/functions/token/gsql_ts_to_epoch_legacy.adoc @@ -0,0 +1,49 @@ += gsql_ts_to_epoch_seconds_legacy() + +Converts a timestamp in canonical string format to Unix epoch time (seconds since `Jan 1, 1970`). +If the timestamp is invalid or earlier than `1970-01-01 00:00:00`, the function returns a user-specified value (0 by default), ensuring backward compatibility and preventing exceptions. + +We also have another timestamp function, xref:ddl-and-loading:functions/token/gsql_ts_to_epoch.adoc[gsql_ts_to_epoch_seconds()], which converts a timestamp to Unix epoch time (seconds since Jan 1st, 1970) and throws an exception instead of returning a user-specified value, if the input is not valid. For broader date range support, consider xref:ddl-and-loading:functions/token/gsql_ts_to_epoch_signed.adoc[gsql_ts_to_epoch_seconds_signed()]. + +== Syntax +`gsql_ts_to_epoch_seconds_legacy(timestamp, defaultTimestamp = 0)` + +== Parameters +timestamp:: +Required. +The timestamp to convert to Unix epoch time. +The timestamp parameter should be in one of the following formats: +* `"%Y-%m-%d %H:%M:%S"` +* `"%Y/%m/%d %H:%M:%S"` +* `"%Y-%m-%dT%H:%M:%S.000z"` +** Text after the dot `.` is ignored + +defaultTimestamp:: +Optional. +If the timestamp is invalid (e.g., before `Jan 1st, 1970`, or an invalid date format), it returns a user-specified value. The default is `0`. + +== Return type +`uint64_t` + +* Returns the epoch seconds for valid timestamps between `1970-01-01 00:00:00` and `9999-12-31 23:59:59`. +* Returns `defaultTimestamp` for abnormal times (pre-1970 or invalid). + +== Example + +---- +// Example with a valid date after 1970 +gsql_ts_to_epoch_seconds_legacy("2022-06-30 22:08:28") -> 1656652105 + +// Example with a date before 1970 (returns default 0) +gsql_ts_to_epoch_seconds_legacy("1969-12-31 23:59:59") -> 0 + +// Example with a date before 1970 and a custom default timestamp +gsql_ts_to_epoch_seconds_legacy("1969-12-31 23:59:59", 999) -> 999 + +// Example with an invalid date (returns default 0) gsql_ts_to_epoch_seconds_legacy("2022-02-30 00:00:00") -> 0 +---- + +[TIP] +==== +Use this function if you want to maintain legacy behavior (prior to the availability of `gsql_ts_to_epoch_signed`), avoid exceptions for invalid or pre-1970 dates, and ensure unsigned integer output. +==== diff --git a/modules/ddl-and-loading/pages/functions/token/gsql_ts_to_epoch_signed.adoc b/modules/ddl-and-loading/pages/functions/token/gsql_ts_to_epoch_signed.adoc new file mode 100644 index 00000000..3643ad63 --- /dev/null +++ b/modules/ddl-and-loading/pages/functions/token/gsql_ts_to_epoch_signed.adoc @@ -0,0 +1,54 @@ += gsql_ts_to_epoch_seconds_signed() + +Converts a timestamp in canonical string format to Unix epoch time (seconds before or after `Jan 1, 1970`). +It supports dates from `0001-01-01` to `9999-12-31`, returning negative epoch values for dates prior to 1970. Invalid or out-of-range dates (e.g., `Feb 30th`) return `defaultTimestamp`. + +We also have another timestamp function, xref:ddl-and-loading:functions/token/gsql_ts_to_epoch.adoc[gsql_ts_to_epoch_seconds()], which converts a timestamp to Unix epoch time (seconds since Jan 1st, 1970) and returns an unsigned integer (`UINT`). For backward compatibility behavior (4.2 or earlier), consider xref:ddl-and-loading:functions/token/gsql_ts_to_epoch_legacy.adoc[gsql_ts_to_epoch_seconds_legacy()]. + +== Syntax +`gsql_ts_to_epoch_seconds_signed(timestamp, defaultTimestamp = 0)` + +== Parameters +timestamp:: +Required. +The timestamp to convert to Unix epoch time. +The timestamp parameter should be in one of the following formats: +* `"%Y-%m-%d %H:%M:%S"` +* `"%Y/%m/%d %H:%M:%S"` +* `"%Y-%m-%dT%H:%M:%S.000z"` +** Text after the dot `.` is ignored + +defaultTimestamp:: +Optional. +If the timestamp is invalid (e.g., out of range or structurally incorrect), it returns the provided default value. The default is `0`. + +== Return type +`int64_t` + +* Returns the epoch seconds for valid timestamps between `0001-01-01 00:00:00` and `9999-12-31 23:59:59`. +* Returns `defaultTimestamp` for invalid times (impossible dates or out-of-range). + +[NOTE] +==== +Timestamps before 1583 use the Gregorian calendar algorithm, so accuracy cannot be guaranteed. Using dates before 1583 is not recommended. +==== + +== Example + +---- +// Example with a valid date after 1970 +gsql_ts_to_epoch_seconds_signed("2022-06-30 22:08:28") -> 1656652105 + +// Example with a date before 1970 (returns a negative epoch value) +gsql_ts_to_epoch_seconds_signed("1969-12-31 23:59:59") -> -1 + +// Example with a date from year 0001 +gsql_ts_to_epoch_seconds_signed("0001-01-01 00:00:00") -> -62135596800 + +// Example with an invalid date (returns default 0) gsql_ts_to_epoch_seconds_signed("2022-02-30 00:00:00") -> 0 +---- + +[TIP] +==== +Choose this function if you need to support negative epoch values for pre-1970 dates, process a broader range of historical data, or require a signed integer output. +==== diff --git a/modules/ddl-and-loading/pages/functions/token/index.adoc b/modules/ddl-and-loading/pages/functions/token/index.adoc index 88f18711..61a61f02 100644 --- a/modules/ddl-and-loading/pages/functions/token/index.adoc +++ b/modules/ddl-and-loading/pages/functions/token/index.adoc @@ -82,8 +82,19 @@ returns that number cast as an integer. |`UINT` |Converts a timestamp in canonical string format to Unix epoch time, which is the int number of -seconds since Jan. 1, 1970. Refer to the timestamp input format note -below. +seconds since Jan. 1, 1970. + +|xref:functions/token/gsql_ts_to_epoch_legacy.adoc[ +pass:[gsql_ts_to_epoch_seconds_legacy(timestamp,
defaultTimestamp = 0)] +] +|`uint64_t` +|Converts a timestamp to Unix epoch time. Returns a default value (`0` or user-specfied) for timestamps before 1970. + +|xref:functions/token/gsql_ts_to_epoch_signed.adoc[ +pass:[gsql_ts_to_epoch_seconds_signed(timestamp,
defaultTimestamp = 0)] +] +|`int64_t` +|Converts a timestamp to Unix epoch time. Supports a wider range of dates, including pre-1970, and returns negative values for those dates. |xref:functions/token/gsql_current_time_epoch.adoc[gsql_current_time_epoch(0)] |`UINT` diff --git a/modules/ddl-and-loading/pages/functions/token_where/gsql_is_not_empty.adoc b/modules/ddl-and-loading/pages/functions/token_where/gsql_is_not_empty.adoc deleted file mode 100644 index 6baf70bf..00000000 --- a/modules/ddl-and-loading/pages/functions/token_where/gsql_is_not_empty.adoc +++ /dev/null @@ -1,21 +0,0 @@ -= gsql_is_not_empty() - -Returns true if a string is empty after removing all white space. -Returns false otherwise. -This function does not alter the input the token. - -== Syntax - -`gsql_is_not_empty( token )` - -== Return value - -`BOOL`. -True if the string is empty after removing all white space from the string. - -== Example - ----- -gsql_is_not_empty("h e ll o") - true -gsql_is_not_empty(" ") -> false ----- \ No newline at end of file diff --git a/modules/ddl-and-loading/pages/functions/token_where/gsql_is_not_empty_string.adoc b/modules/ddl-and-loading/pages/functions/token_where/gsql_is_not_empty_string.adoc new file mode 100644 index 00000000..b735ebc6 --- /dev/null +++ b/modules/ddl-and-loading/pages/functions/token_where/gsql_is_not_empty_string.adoc @@ -0,0 +1,25 @@ +:page-aliases: gsql_is_not_empty.adoc + += gsql_is_not_empty_string() + +Returns true if a string is not empty after removing all white space. +Returns false otherwise. +This function does not alter the input token. + +== Syntax + +`gsql_is_not_empty_string(token)` + +== Return value + +`BOOL` + +Returns `true` if the string is not empty after removing all white space. +Returns `false` otherwise. + +== Example + +---- +gsql_is_not_empty_string("h e ll o") -> true +gsql_is_not_empty_string(" ") -> false +---- diff --git a/modules/ddl-and-loading/pages/managing-loading-job.adoc b/modules/ddl-and-loading/pages/managing-loading-job.adoc index 4d2b3bed..69142863 100644 --- a/modules/ddl-and-loading/pages/managing-loading-job.adoc +++ b/modules/ddl-and-loading/pages/managing-loading-job.adoc @@ -180,8 +180,11 @@ If an object level error or failed condition occurs, only the corresponding obje | Invalid primary id | The number of invalid objects caused by wrong data format for the PRIMARY_ID type -| incorrect fixed binary length +| Incorrect fixed binary length | The number of invalid objects caused by the mismatch of the length of the data to the type defined in the schema + +| Token Bank Exception +| The number of exceptions thrown by user-defined token functions. |=== Note that failing a `WHERE` clause is not necessarily a bad result. @@ -293,4 +296,4 @@ Of the 6 valid lines, * Two lines (Lines 4 and 5) do not pass the `WHERE` clause. The errors that appear are the first line with an error in each batch in the loading job. -Up to 100 sample lines showing errors appear in the log. \ No newline at end of file +Up to 100 sample lines showing errors appear in the log. diff --git a/modules/ddl-and-loading/pages/modifying-a-graph-schema.adoc b/modules/ddl-and-loading/pages/modifying-a-graph-schema.adoc index bff57703..2cebf3d8 100644 --- a/modules/ddl-and-loading/pages/modifying-a-graph-schema.adoc +++ b/modules/ddl-and-loading/pages/modifying-a-graph-schema.adoc @@ -1,25 +1,46 @@ = Modifying a Graph Schema +:description: How to create and run schema changes; the side effects of schema change; global vs. local schema changes. -After a graph schema has been created , it can be modified. Data already stored in the graph and which is not logically part of the change will be retained. For example, if you had 100 Book vertices and then added an attribute to the Book schema, you would still have 100 Books, with default values for the new attribute. If you dropped a Book attribute, you still would have all your books, but one attribute would be gone. +GSQL lets you modify a graph schema -- add or remove vertex types, edge types, or attributes. Data already stored in the graph and which is not logically part of the change is unaffected. +For example, if you had 100 Book vertices and then added an attribute to the Book schema, you would still have 100 Books, with default values for the new attribute. If you dropped a Book attribute, you still would have all your books, but one attribute would be gone. -To safely update the graph schema, the user should follow this procedure: +The schema change workflow is as follows: -* Create a schema change job, which defines a sequence of `ADD`, `ALTER` and/or `DROP` statements. -* Run the schema change job (using *`RUN SCHEMA_CHANGE JOB `*), which will do the following: -** Attempt the schema change. -** If the change is successful, invalidate any loading job or query definitions which are incompatible with the new schema. -** if the change is unsuccessful, report the failure and return to the state before the attempt. +. xref:#_create_global_schema_change_job[Create a schema change job], which defines a sequence of `ADD`, `ALTER` and/or `DROP` statements. + +. [Recommended] If your schema change will drop any elements, prescreen your xref:#_side_effects_of_schema_change[queries and loading jobs for expected side effects]. + +. Either stop all database activity or read carefully the section on xref:#_dynamic_schema_change_abilities_and_limitations[dynamic schema change] to see what concurrent activity is reasonable. + +. xref:#_run_global_schema_change_job[Run the schema change job], which will do the following: +** It attempts the schema change. +** It aborts in-progress loading jobs or queries, depending on the options selected by the user. +** When the schema change is complete, xref:#_side_effects_of_schema_change[it invalidates any loading job or query definitions which are incompatible] with the new schema. +** If the change was unsuccessful, it reports the failure and return to the state before the attempt. + +. Review loading jobs and queries which we invalidated. +If they are still wanted, revise them and reinstall them to be consistent with the new schema. + + +== Side Effects of Schema Change + +When a schema changes, this has side effects on loading jobs and queries, both ones in the catalog and especially ones which may be actively running during the schema change. [WARNING] ==== A schema change will invalidate any loading jobs or query which relate to an altered part of the schema. Specifically: -* A loading job becomes invalid if it refers to a vertex or and an edge which has been *dropped* (deleted) or *altered* . -* A query becomes invalid if it refers to a vertex, and edge, or an attribute which has been *dropped* . +* A loading job becomes invalid if it refers to a vertex type or an edge type that has been DROPPED or ALTERED. -Invalid loading jobs are dropped, and invalid queries are uninstalled. After the schema update, the user will need to create and install new load and query jobs based on the new schema. +* A query becomes invalid if it refers to a vertex type, edge type, or an attribute of a type that has been DROPPED. + +Invalid loading jobs are moved to the `disabled` state, and invalid queries are uninstalled. After the schema change, a user will need to create and install new load and query jobs based on the new schema. ==== +Prior to 4.2, invalid loading jobs would be dropped (removed) from the catalog. Beginning with 4.2, loading jobs invalidated by a schema change are retained but marked as `disabled`. They cannot be re-enabled. They are retained for reference so users can read them, as a guide to creating a new loading job that is consistent with the new schema. + +Even queries which are not invalidated by a schema change may behave differently, if they traverse _all_ vertices or _all_ edges. + [WARNING] ==== Load or query operations which begin before the schema change will be completed based on the pre-change schema. Load or query operations which begin after the schema change, and which have not been invalidated, will be completed based on the post-change schema. @@ -28,6 +49,42 @@ Load or query operations which begin before the schema change will be completed Schema changes that are performed during times with high query or data loading volume may have a chance of failure. It is considered good practice to perform schema changes during times of low graph activity. +== Dynamic Schema Change - Abilities and Limitations + +Dynamic Schema Change (DSC) acts as a traffic manager for schema change jobs. First, if there are any active loading jobs in progress when a schema change is requested, and the schema change affects a graph element included in the loading job, DSC should pause the schema change until the loading job completes. + +Once the schema change begins, DSC enables a modest amount of database activity (queries and loading) during a schema change, but ONLY if those operations do not involve graph elements affected by the schema change. If the activity level is too high, there is a risk of either the schema change job not succeeding, the concurrent database activity not succeeding, or both. + +[WARNING] +==== +For maximum safety, is it best to halt all graph activity before and during a schema change. If a schema change job fails, it can leave the graph in an inconsistent state. +==== + +[IMPORTANT] +==== +Perform schema changes only when no active queries or loading jobs are running to avoid data consistency and application errors. +Always abort ongoing jobs before initiating the schema change. +==== + +=== Do's and Don'ts for Schema Change + +Because the demands of each graph activity vary, there is no universal way to state what level of concurrent graph activity can be handled by dynamic schema change. + +*Do's:* + +* *Do backup your data before performing a schema change* as a precaution. +* *Do perform schema changes only during no- or low-traffic periods.* + +*Don'ts:* + +* *Don’t change the schema during high-traffic periods.* Schema changes during heavy operations may cause system conflicts and errors. +* *Don't run queries and loading jobs which you know are affected by the schema* as they will be invalidated. + +*For maximum safety:* + +* *Don’t run any queries or loading jobs during schema changes.* + + [#_global_vs_Local_schema_changes] == Global vs. local schema changes @@ -36,7 +93,8 @@ It is considered good practice to perform schema changes during times of low gra Users must have the global scope to interact with global schema change jobs (create, delete, run). See xref:_use_global[]. ==== -=== `USE GLOBAL` + +=== USE GLOBAL The `USE GLOBAL` command changes a superuser's mode to Global mode. In global mode, a superuser can define or modify global vertex and edge types, as well as specifying which graphs use those global types. @@ -261,10 +319,93 @@ CREATE SCHEMA_CHANGE JOB add_reviews FOR GRAPH Book_Rating { RUN SCHEMA_CHANGE JOB add_reviews ---- -=== -N Option (Local and Global) +=== Run Schema Change Options + +==== `-warn` + +Before beginning the schema change, check to see if any loading jobs in progress have a schema conflict with the planned changes. +If so, ask the user if they want to abort the loading jobs. + +Example: + +[console] +---- +GSQL > RUN GLOBAL SCHEMA_CHANGE JOB change_vt_comment -warn + +[Warning] This schema change job will disrupt the following loading jobs: + - Graph test_graph: + load_ldbc_snb +Do you want to abort these loading jobs to proceed the schema change? (Y/n):yes + +WARNING: When modifying the graph schema, reinstalling all affected queries is required, and the duration of this process may vary based on the number and complexity of the queries. To skip query reinstallation, you can run with the '-N' option, but manual reinstallation of queries will be necessary afterwards. +[Warning] Following loading jobs will be aborted: + + - Graph test_graph: + load_ldbc_snb + +Kick off global schema change job change_vt_comment +Doing schema change on graph 'test_graph' (current version: 0) + +Doing schema change on the global schema (current version: 0) +Trying to drop attribute 'content' from global vertex 'Comment'. +Loading job 'load_ldbc_snb' from graph 'test_graph' will be disabled after schema change. + +Graph test_graph updated to new version 1 +Global schema change succeeded. +---- + +==== `-force` + +Before beginning the schema change, check to see if any loading jobs in progress have a schema conflict with the planned changes. If so, abort the loading jobs. + +Example: +---- +GSQL > RUN GLOBAL SCHEMA_CHANGE JOB change_vt_comment -force + +WARNING: When modifying the graph schema, reinstalling all affected queries is required, and the duration of this process may vary based on the number and complexity of the queries. To skip query reinstallation, you can run with the '-N' option, but manual reinstallation of queries will be necessary afterwards. +[Warning] Following loading jobs will be aborted: + + - Graph test_graph: + load_ldbc_snb + +Kick off global schema change job change_vt_comment +Doing schema change on graph 'test_graph' (current version: 0) + +Doing schema change on the global schema (current version: 0) +Trying to drop attribute 'content' from global vertex 'Comment'. +Loading job 'load_ldbc_snb' from graph 'test_graph' will be disabled after schema change. + +Graph test_graph updated to new version 1 +Global schema change succeeded. +---- + + + + + + +==== `-N` + + + +Option `-N`, for both global and local scopes, marks all queries as invalid and the user will need to manually re-install the invalid queries. + +Local jobs with the `-N` option will skip recompile and reinstall queries created for the local graph. + +.Example +[source,gsql] +---- +RUN SCHEMA_CHANGE JOB test_job -N +---- + +Global jobs with the `-N` option will skip recompile and re-install queries. + +.Example +[source,gsql] +---- +RUN GLOBAL SCHEMA_CHANGE JOB test_job -N +---- -Additionally, an option `-N` is currently supported for both local and global schema change jobs. -See xref:_n_option[] for more details. == `DROP JOB SCHEMA_CHANGE` @@ -454,30 +595,10 @@ CREATE GLOBAL SCHEMA_CHANGE JOB alter_friendship_make_library { RUN GLOBAL SCHEMA_CHANGE JOB alter_friendship_make_library ---- -=== `-N` Option +=== Run Global Schema Change Options -Additionally, an option `-N` is currently supported for both local and global schema change jobs. +RUN GLOBAL SCHEMA CHANGE JOB has the xref:#_run_schema_change_options[same options as RUN SCHEMA CHANGE JOB]. -[NOTE] -==== -Option `-N`, for both global and local scopes, will mark the queries as deprecated and the user will need to manually re-install the deprecated queries. -==== - -Local jobs with the `-N` option will skip recompile and reinstall queries created for the local graph. - -.Example -[source,gsql] ----- -RUN SCHEMA_CHANGE JOB test_job -N ----- - -Global jobs with the `-N` option will skip recompile and re-install queries. - -.Example -[source,gsql] ----- -RUN GLOBAL SCHEMA_CHANGE JOB test_job -N ----- === Impact Warning @@ -547,6 +668,7 @@ DROP JOB alter_friendship_make_library == `DROP ALL` -The DROP ALL command clears all graph data, all graph schemas, all loading jobs, and all queries. It should only be used when the intent is to erase an entire database design and to start over. +The `DROP ALL` command clears the entire graph store (i.e. deletes all data) and removes all data-related definitions from the catalog: vertex types, edge types, graph types, jobs, and queries. It will also erase graph-specific roles. + +See xref:defining-a-graph-schema.adoc#_drop_all[DROP ALL] for more details. -This command is only available to superusers and only when they are in global mode. diff --git a/modules/ddl-and-loading/pages/running-a-loading-job.adoc b/modules/ddl-and-loading/pages/running-a-loading-job.adoc index e4e89845..9d798cb6 100644 --- a/modules/ddl-and-loading/pages/running-a-loading-job.adoc +++ b/modules/ddl-and-loading/pages/running-a-loading-job.adoc @@ -41,7 +41,7 @@ There are options to end the job when it reaches a specified level of errors. [NOTE] User privileges for running loading jobs are treated as separate from privileges regarding reading and writing data to vertices and edges. A user can create and run loading jobs even without the privileges to modify vertex and edge data. -For more information, see xref:tigergraph-server:user-access:access-control-model.adoc[]. +For more information, see xref:{page-component-version}@tigergraph-server:user-access:access-control-model.adoc[]. [#_run_loading_job] === RUN LOADING JOB @@ -107,10 +107,14 @@ There are two possible cases where an input line may be rejected: The percentage number following `-max_percent_error` **is required** if the option is provided. Otherwise, a parsing error will appear. +The xref:tigergraph-server:api:gsql-endpoints.adoc#_run_a_loading_job[`maxPercentError`] key for running a loading job via the REST API has the same meaning as the `-max_percent_error` option in GSQL. + ==== `-max_error me` The `-max_error` option instructs the loader process to abort the loading job if the number of data lines in the input batch that are rejected exceeds `me`, where `me` is an integer between 0 and 2147483647. This option is analogous to the `-max_percent_error` option. +The xref:tigergraph-server:api:gsql-endpoints.adoc#_run_a_loading_job[`maxNumError`] key for running a loading job via the REST API has the same meaning as the `-max_error` option in GSQL. + === Parameters Below are the parameters available for the `RUN QUERY` command introduced by the `USING` clause. diff --git a/modules/ddl-and-loading/partials/load-statement.adoc b/modules/ddl-and-loading/partials/load-statement.adoc index d65d1851..04cf9d80 100644 --- a/modules/ddl-and-loading/partials/load-statement.adoc +++ b/modules/ddl-and-loading/partials/load-statement.adoc @@ -238,17 +238,16 @@ Therefore, we recommend that if multiple destination clauses share the same sour |=== |Parameter | Description |Allowed values |`SEPARATOR` -|Specifies the special character that separates tokens -(columns) in the data file. +a|Specifies the special character or character sequence that separates tokens (columns) in the data file. Examples of character sequences, + +* \|#\| +* `\t\xy` for the combination of `tab` and ASCII decimal code `xy` a| -Any single ASCII character. +Any ASCII characters, maximum length is 24. Default: comma `,` -* `\t for tab` -* `\xy` for ASCII decimal code `xy` - |`EOL` |Specifies the end-of-line character. a| @@ -294,7 +293,7 @@ header has been defined in the loading job, rather than in the data file |`REJECT_LINE_RULE` |If the filter expression evaluates to true, then do not use this input data line. -Not supported in a xref:tigergraph-server:data-loading:index.adoc[ loading job]. +Not supported in a xref:{page-component-version}@tigergraph-server:data-loading:index.adoc[ loading job]. |name of filter from a preceding `DEFINE INPUT_LINE_FILTER` statement @@ -397,10 +396,50 @@ The JSON loader ignores the order and accesses the fields by the nested key name | 3 |=== +==== Loading data from a nested JSON array + +To extract values from arrays of JSON objects, use the `flatten_json_array()` function. + +For example, consider the following JSON object: + +[source,json] +---- +{ + "id": 1234, + "nested_object": { + "id": 2345, + "neighbors": [ + { "id": 1, "name": "foo" }, + { "id": 2, "name": "bar" }, + { "id": 3, "name": "baz" } + ] + } +} +---- + +To load each object in the `neighbors` array as a vertex, first flatten the array into a temporary table, then load the data: + +[source,gsql] +---- +CREATE VERTEX Person (PRIMARY_ID id INT, name STRING) +CREATE GRAPH example_graph (*) + +CREATE LOADING JOB load_neighbors FOR GRAPH example_graph { + LOAD "data.jsonl" TO TEMP_TABLE t(id, name) + VALUES (flatten_json_array($"nested_object":"neighbors", $"id", $"name")) + USING JSON_FILE="true"; + + LOAD TEMP_TABLE t TO VERTEX Person + VALUES ($"id", $"name"); +} +---- + +In this example, the `flatten_json_array()` function extracts each object in the `neighbors` array and maps the fields to the temporary table. Each row in the temporary table is then loaded as a vertex. + === Loading Parquet data TigerGraph can load data from Parquet files using our loader. -For more details on how to set up a Kafka data streaming connector and loading jobs, see xref:tigergraph-server:data-loading:data-loading-overview.adoc[]. +For more details on how to set up a Kafka data streaming connector and loading jobs, see xref:{page-component-version}@tigergraph-server:data-loading:data-loading-overview.adoc[]. CAUTION: When loading Parquet data, INT96 data types are not supported. If your data source uses INT96 data types, the corresponding attribute in your graph will be left empty. diff --git a/modules/intro/images/vector.png b/modules/intro/images/vector.png new file mode 100644 index 00000000..335aac93 Binary files /dev/null and b/modules/intro/images/vector.png differ diff --git a/modules/intro/pages/index.adoc b/modules/intro/pages/index.adoc index 4e8882f3..9a0873cd 100644 --- a/modules/intro/pages/index.adoc +++ b/modules/intro/pages/index.adoc @@ -1,61 +1,63 @@ -= GSQL Language Reference += Query Language Reference :page-aliases: intro.adoc -The GSQL™ software program is the TigerGraph comprehensive environment for designing graph schemas, loading and managing data to build a graph, and querying the graph to perform data analysis. +The *GSQL™* software program is the TigerGraph comprehensive environment for designing graph schemas, loading and managing data to build a graph, and querying the graph to perform data analysis. TigerGraph now also supports *OpenCypher* and the pattern matching portion of *GQL*, within the same execution engine. -In short, TigerGraph users do most of their work via the GSQL program. -This document presents the syntax and features of the GSQL language. - -== Get to Know GSQL +== Graph and Vector Querying [.home-card,cols="2,2",grid=none,frame=none, separator=¦] |=== ¦ image:getstarted-homecard.png[alt=getstarted,width=74,height=74] *Tutorials* -A set of step-by-step tutorials to help you get started using GSQL in TigerGraph. +Step-by-step tutorials to help you get started creating graphs and querying. -https://github.com/tigergraph/ecosys/blob/master/demos/guru_scripts/docker/tutorial/4.x/README.md[GSQL Tutorial |] -xref:gsql-ref:tutorials:accumulators-tutorial.adoc[Accumulators Tutorial] +https://github.com/tigergraph/ecosys/blob/master/tutorials/GSQL.md[GSQL Tutorial] | +xref:gsql-ref:tutorials:accumulators-tutorial.adoc[Accumulators] | +https://github.com/tigergraph/ecosys/blob/master/tutorials/Cypher.md[OpenCypher] | +https://github.com/tigergraph/ecosys/blob/master/tutorials/VectorSearch.md[VECTOR search] //xref:gsql-ref:tutorials:pattern-matching/index.adoc[Pattern Maching Tutorial |] +¦ +image:vector.png[alt=types,width=74,height=74] +*Hybrid Vector Search* + +Use graph+vector search for powerfully selective searches, supercharging AI + +xref:vector:index.adoc[] | +link:https://github.com/tigergraph/ecosys/blob/master/tutorials/VectorSearch.md[Hybrid Graph+Vector Search Tutorial] + ¦ image:img.png[alt=graphstudio,width=74,height=74] *openCypher in GSQL* TigerGraph’s GSQL query language supports many openCypher features. -xref:openCypher-in-gsql:openCypher-in-gsql.adoc[openCypher in GSQL |] -xref:openCypher-in-gsql:openCypher-gsql-from-clause-extension.adoc[Clause Extension |] -xref:openCypher-in-gsql:openCypher-in-gsql-web-shell.adoc[openCypher in Web Shell] +link:https://github.com/tigergraph/ecosys/blob/master/tutorials/Cypher.md[openCypher in GSQL Tutorial (on GitHub) ] | +xref:openCypher-in-gsql:index.adoc[] ¦ image:lang.png[alt=basics,width=74,height=74] -*System & Language Basics* +*Language Basics* -Learn the xref:gsql-ref:basics:system-and-language-basics.adoc[Basic Elements] that make up the GSQL Data Definition. - -¦ -image:attrbutes-homecard.png[alt=types,width=74,height=74] -*Attribute Data Types* - -Learn about xref:gsql-ref:ddl-and-loading:attribute-data-types.adoc[Vertex and Edge Attributes] and the different data types that can be stored in them. +Learn xref:gsql-ref:basics:running-gsql.adoc[How to run GSQL] and +xref:gsql-ref:ddl-and-loading:attribute-data-types.adoc[Database Data Types]. ¦ image:schema-homecard.png[alt=types,width=74,height=74] -*Schema Definition* +*Define a Schema* Use the Database Definition Language (DDL) syntax to define the xref:gsql-ref:ddl-and-loading:index.adoc[schema] the blueprint for data elements in a database. ¦ image:querying-homecard.png[alt=query,width=74,height=74] -*Querying* +*Graph Querying* xref:gsql-ref:querying:index.adoc[GSQL Query Language] is a language for the exploration and analysis of large scale graphs. ¦ image:DataLoading-Homecard.png[alt=loadingjobs,width=74,height=74] -*Loading Jobs* +*Loading Data* xref:gsql-ref:ddl-and-loading:loading-jobs.adoc[Loading Jobs] are a unique and powerful feature used to load data into the database. @@ -69,14 +71,3 @@ xref:gsql-ref:appendix:cheat-sheets.adoc[Cheat Sheets |] xref:gsql-ref:appendix:gsql-style-guide.adoc[GSQL Style Guide] |=== - - - - - - - - - - - diff --git a/modules/openCypher-in-gsql/nav.adoc b/modules/openCypher-in-gsql/nav.adoc index c77a3da7..2fdf33ae 100644 --- a/modules/openCypher-in-gsql/nav.adoc +++ b/modules/openCypher-in-gsql/nav.adoc @@ -1,4 +1,3 @@ -* openCypher -** xref:openCypher-in-gsql.adoc[] -** xref:openCypher-in-gsql-web-shell.adoc[] -** xref:openCypher-gsql-from-clause-extension.adoc[] +** xref:index.adoc[openCypher in GSQL] +*** xref:openCypher-in-gsql-web-shell.adoc[] +*** xref:openCypher-gsql-from-clause-extension.adoc[] diff --git a/modules/openCypher-in-gsql/pages/index.adoc b/modules/openCypher-in-gsql/pages/index.adoc new file mode 100644 index 00000000..a7d6fb79 --- /dev/null +++ b/modules/openCypher-in-gsql/pages/index.adoc @@ -0,0 +1,395 @@ += openCypher in GSQL +:description: Summary of TigerGraph's level of support for the openCypher query language. +:page-aliases: openCypher-in-gsql.adoc, openCypher-in-gsql/openCypher-in-gsql.adoc + +openCypher is a popular open-source declarative query language for property graphs. More about openCypher can be found at http://opencypher.org[openCypher.org]. + +TigerGraph supports the majority of openCypher features, embedded within its native GSQL language. This page lists the features currently xref:_opencypher_features_in_gsql[supported] and features xref:_opencypher_features_not_yet_supported[not yet supported ]. + +It also describes how the different xref:#_key_differences_gsql_vs_opencypher[schema models in OpenCypher vs. GSQL] affect some queries. + + +[NOTE] +==== +From version 4.1.2, certain restrictions on the `MATCH` and `WITH` clauses have been eliminated. +==== + +== openCypher Features in GSQL +=== Clauses + +[cols="1,2"] +|=== +|Clause |Description + +|DELETE |Delete graph elements — nodes and relationships. + +Any node to be deleted must also have all associated relationships explicitly deleted. + +|DETACH DELETE |Writing Delete a node or set of nodes. + +All associated relationships will automatically be deleted. + +|LIMIT |Reading sub-clause A sub-clause used to constrain the number of records in the output. + +|MATCH |Reading Specify the patterns to search for in the database. + +See below for restrictions before version *4.1.2*. + +|MANDATORY MATCH |Reading Specify the patterns to search for in the database, and fail if no match is found. + +|OPTIONAL MATCH |Reading Specify the patterns to search for in the database while using nulls for missing parts of the pattern. + +|ORDER BY [ASC[ENDING] DESC[ENDING]] |Reading sub-clause A sub-clause following + +|RETURN or WITH |Specifying that the output should be sorted in either ascending (the default) or descending order. + +|RETURN … [AS] |Projecting Defines what to include in the query result set. + +|SKIP |Reading/Writing A sub-clause defining from which record to start including the records in the output. + +|WHERE |Reading sub-clause A sub-clause used to add constraints to the patterns in a MATCH clause, or to filter the results of a WITH clause. + +|WITH … [AS] |Projecting Allows query parts to be chained together, piping the results from one to be used as starting points or criteria in the next. + +See below for restrictions before version *4.1.2*. +|=== + +=== Operators +[cols="1,3"] +|=== +|Operator |Description + +|% |Mathematical Modulo division + +|* |Mathematical Multiplication + +|+ |Mathematical Addition + +|+ |String Concatenation + +|+ |List Concatenation + +|- |Mathematical Subtraction or unary minus + +|. |General Property access + +|/ |Mathematical Division + +|< |Comparison Less than + +|< = |Comparison Less than or equal to + +|<> |Comparison Inequality + +|= |Comparison Equality + +|> |Comparison Greater than + +|>= |Comparison Greater than or equal to + +|AND |Boolean Conjunction + +|CONTAINS |String comparison Case-sensitive inclusion search + +|DISTINCT |General Duplicate removal + +|ENDS WITH |String comparison Case-sensitive suffix search + +|IN List |List element existence check + +|IS NOT NULL |Comparison Non-null check + +|IS NULL |Comparison null check + +|NOT |Boolean Negation + +|OR |Boolean Disjunction + +|STARTS WITH |String comparison Case-sensitive prefix search + +|XOR |Boolean Exclusive disjunction + +|[ ] |General Subscript (dynamic property access) + +|[ ] |List Subscript (accessing element(s) in a list) + +|^ |Mathematical Exponentiation +|=== + +=== Functions + +[%autowidth] +|=== +|Operator | Value type | Description + +|abs() |Numeric | Returns the absolute value of a number. + +|acos() |Numeric | Returns the arccosine of a number in radians. + +|asin() |Numeric | Returns the arcsine of a number in radians. + +|atan() |Numeric | Returns the arctangent of a number in radians. + +|atan2() |Numeric | Returns the arctangent2 of a set of coordinates in radians. + +|avg() |Numeric | Returns the average of a set of numeric values. + +|ceil() |Numeric | eturns the smallest floating point number that is greater than or equal to a number and equal to a mathematical integer. + +|coalesce() |Scalar |Returns the first non-null value in a list of expressions. + +|cos() |Numeric | Returns the cosine of a number. + +|cot() |Numeric | Returns the cotangent of a number. + +|count() |Numeric | Returns the number of values or records. + +|degrees() |Numeric | Converts radians to degrees. + +|e() |Numeric | Returns the base of the natural logarithm, e. + +|elementId() |Scalar |Returns the String id of a relationship or node. + +|exp() |Numeric | Returns e^n, where e is the base of the natural logarithm, and n is the value of the argument expression. + +|floor() |Numeric | Returns the largest floating point number that is less than or equal to a number and equal to a mathematical integer. + +|head() |Scalar |Returns the first element in a list. + +|id() |Scalar |Returns the id of a relationship or node. + +|labels() |List |Returns a list containing the string representations for all the labels of a node. + +|last() |Scalar |Returns the last element in a list. + +|left() |String |Returns a string containing the specified number of leftmost characters of the original string. + +|log() |Numeric | Returns the natural logarithm of a number. + +|log10() |Numeric | Returns the common logarithm (base 10) of a number. + +|lTrim() |String |Returns the original string with leading whitespace removed. + + +|max() |Numeric | Returns the maximum value in a set of values. + +|min() |Numeric | Returns the minimum value in a set of values. + +|pi() |Numeric | Returns the mathematical constant pi. + +|radians() |Numeric | Converts degrees to radians. + +|rand() |Numeric | Returns a random floating point number in the range from 0 (inclusive) to 1 (exclusive); i.e. [0, 1). + +|range() |List |Returns a list comprising all integer values within a specified range. + +|replace() |String |Returns a string in which all occurrences of a specified string in the original string have been replaced by another (specified) string. + +|reverse() |String |Returns a string in which the order of all characters in the original string have been reversed. + +|right() |String |Returns a string containing the specified number of rightmost characters of the original string. + +|round() |Numeric |Returns the value of a number rounded to the nearest integer. + +|rTrim() |String |Returns the original string with trailing whitespace removed. + +|sign() |Numeric |Returns the signum of a number: 0 if the number is 0, -1 for any negative number, and 1 for any positive number. + +|sin() |Numeric | Returns the sine of a number. + +|size() |Numeric | Returns the number of items in a list. (When applied to a list) + +|split() |List |Returns a list of strings resulting from the splitting of the original string around matches of the given delimiter. + +|sqrt() |Numeric | Returns the square root of a number. + +|stDev() |Numeric | Returns the standard deviation for the given value over a group for a sample of a population. + +|stDevP() |Numeric | Returns the standard deviation for the given value over a group for an entire population + +|substring() |String |Returns a substring of the original string, beginning with a 0-based index start and length. + +|sum() |Numeric | Returns the sum of a set of numeric values. + +|tail() |List |Returns all but the first element in a list. + +|tan() |Numeric | Returns the tangent of a number. + +|timestamp() |Scalar |Returns the difference, measured in milliseconds, between the current time and midnight, January 1, 1970 UTC. + +|trim() |String |Returns the original string with leading and trailing whitespace removed. + +|toLower() |String |Returns the original string in lowercase. + +|toString() |String |Converts an integer, float or boolean value to a string. + +|toUpper() |String |Returns the original string in uppercase. + +|toBoolean() |Scalar |Converts a string value to a boolean value. + +|toFloat() |Scalar |Converts an integer or string value to a floating point number. + +|toInteger() |Scalar |Converts a floating point or string value to an integer value. + +|type() |Scalar |Returns the string representation of the relationship type. +|=== + +=== Expressions +[cols="1,3"] +|=== +|Expression |Description + +|CASE |A generic conditional expression, similar to if/else statements available in other languages. +|=== + +== openCypher Features Not Yet Supported +=== Clauses +[cols="1,3"] +|=== +|Clause |Description + +|CALL […YIELD] |Reading/Writing Invoke a procedure deployed in the database. + +|CREATE |Writing create nodes and relationships. + +|MERGE |Reading/Writing Ensures that a pattern exists in the graph. Either the pattern already exists, or it needs to be created. + +|REMOVE |Writing Remove properties and labels from nodes and relationships. + +|SET |Writing Update labels on nodes and properties on nodes and relationships. + +|UNION |Set operations Combines the result of multiple queries. Duplicates are removed. + +|UNION ALL |Set operations Combines the result of multiple queries. Duplicates are retained. + +|UNWIND … [AS] |Projecting Expands a list into a sequence of records. +|=== + +=== Operators +N/A + +=== Functions + +[%autowidth] +|=== +| Function | Value Type | Description + +|collect() |Numeric | Returns a list containing the values returned by an expression. + +|endNode() |Scalar |Returns the end node of a relationship. + +|exists() |Boolean | Returns true if a match for the pattern exists in the graph, or if the specified property exists in the node, relationship or map. + +|keys() |List |Returns a list containing the string representations for all the property names of a node, relationship, or map. + +|length() |Numeric | Returns the length of a path. + +|nodes() |List |Returns a list containing all the nodes in a path. + +|percentileCont() |Numeric | Returns the percentile of the given value over a group using linear interpolation. + +|percentileDisc() |Numeric | Returns the percentile of the given value over a group using a rounding method. + +|properties() |Map | Returns a map containing all the properties of a node or relationship. + +|relationships() |List |Returns a list containing all the relationships in a path. + +|reverse() |List |Returns a list in which the order of all elements in the original list have been reversed. + +|size() of a pattern expression |Numeric | Returns the number of subgraphs matching the pattern expression. + +|size() of a string |Numeric | Returns the size of a string. + +|startNode() |Scalar |Returns the start node of a relationship. +|=== + +=== Syntax + +These were limitations before *4.1.2* – certain openCypher syntax were not supported: + +* Queries with a *WITH* clause that *does not* implicitly group by exactly one vertex variable. + +. 0 vertex variables as group key +[source,gsql] +MATCH (u:User {name: "John"}) // find all users with the same friend count as John +WITH u.friendCount AS fc // note, u not included in group key list +MATCH (o:User {friendCount: fc}) +… + +. More than 1 vertex variables as group key +[source,gsql] +MATCH (u1) -[:communication]- (x) -[:communication]- (u2) +WITH u1, u2, COUNT(x) // we support only u1 or only u2 in list +… + +* Queries introducing path variables +[source,gsql] +MATCH p = (u1) -[e1:communication]- (x) -[e2:communication]- (u2) // p is path var +… + +* Queries whose *MATCH* pattern *does not* include at least one vertex variable from immediately preceding *WITH* clause. +[source,gsql] +MATCH (u:user) -[:communication]- (o) +WITH u, … +MATCH (x) -[:communication]-(y) // this pattern must refer to u +… + +* Queries with disconnected *MATCH* pattern fragments +[source,gsql] +MATCH (x:user), (y:user) +WHERE x.friendCount = y.friendCount +… + +* Pattern fragments (x:user) and (y:user) *are not* connected by edge traversal or by sharing vertex variables. + +[#_key_differences_gsql_vs_opencypher] +== OpenCypher vs. GSQL Schema Models + +GSQL, the language and storage engine, is strongly typed and *schema-first*: + +* Every vertex and edge belongs to a previously defined _type_. +* Each type had a characteristics set of properties (attributes); there are no optional properties. + +OpenCypher is *schema-optional*: + +* A vertex or edge _may_ have a _label_. +* A label _may_ be associated with characteristic set of properties. +* An individual vertex or edge could have additional properties. + +This fundamental difference impacts how OpenCypher queries behave in each system. + +=== Example + +Consider the following OpenCypher query: + +[source,gsql] +MATCH (p) +RETURN p.firstName, p.year + +==== How GSQL OpenCypher mode Interprets This Query + +Since GSQL OpenCypher enforces a predefined schema, the query: + +* Only considers vertex types that contain both `firstName` and `year` attributes +* Returns values only if both attributes exist in a given vertex type + +If a vertex type does not have both attributes, it is ignored entirely. + +==== How OpenCypher Interprets This Query + +OpenCypher does not enforce a schema, so the query: + +* Processes all vertex types, regardless of their attributes +* Returns values for existing attributes but returns `NULL` for attributes that do not exist + +[#_key_considerations] +[#_importance] +==== Key Considerations + +For users migrating from OpenCypher to GSQL OpenCypher, it is important to understand that: + +* In GSQL, queries must align with the predefined schema. +* Unlike OpenCypher, GSQL does not return NULL for missing attributes: if a vertex does not contain all required attributes, it is not included in the result. +* A query attempting to access a non-existent attribute in GSQL may either return no results or be rejected if no matching vertex type exists. + +By understanding this distinction, users can write more effective OpenCypher queries tailored to GSQL OpenCypher’s schema-first approach. diff --git a/modules/openCypher-in-gsql/pages/openCypher-in-gsql-web-shell.adoc b/modules/openCypher-in-gsql/pages/openCypher-in-gsql-web-shell.adoc index d9736951..9e1f1330 100644 --- a/modules/openCypher-in-gsql/pages/openCypher-in-gsql-web-shell.adoc +++ b/modules/openCypher-in-gsql/pages/openCypher-in-gsql-web-shell.adoc @@ -14,7 +14,7 @@ Follow these two simple rules: . Replace the body of the query procedure with OpenCypher instead of GSQL. End with a `RETURN` clause. -For more details on the current openCypher support, see xref:openCypher-in-gsql.adoc[]. +For more details on the current openCypher support, see xref:index.adoc[]. == Example: Interpreted Query diff --git a/modules/openCypher-in-gsql/pages/openCypher-in-gsql.adoc b/modules/openCypher-in-gsql/pages/openCypher-in-gsql.adoc deleted file mode 100644 index 77a72688..00000000 --- a/modules/openCypher-in-gsql/pages/openCypher-in-gsql.adoc +++ /dev/null @@ -1,326 +0,0 @@ -= openCypher in GSQL - - -openCypher is a popular open-source declarative query language for property graphs. More about openCypher can be found at http://opencypher.org[openCypher.org]. - -TigerGraph's GSQL query language supports many openCypher features. This page lists the features currently xref:_opencypher_features_in_gsql[supported] and features xref:_opencypher_features_not_yet_supported[not yet supported ]. - -To see how to run openCypher on the TigerGraph platform, see xref:openCypher-in-gsql.adoc[]. - -== openCypher Features in GSQL -=== Clauses - -[cols="1,1"] -|=== -|Clause |Description - -|DELETE |Delete graph elements — nodes and relationships. - -Any node to be deleted must also have all associated relationships explicitly deleted. - -|DETACH DELETE |Writing Delete a node or set of nodes. - -All associated relationships will automatically be deleted. - -|LIMIT |Reading sub-clause A sub-clause used to constrain the number of records in the output. - -|MATCH |Reading Specify the patterns to search for in the database. - -|MANDATORY MATCH |Reading Specify the patterns to search for in the database, and fail if no match is found. - -|ORDER BY [ASC[ENDING] DESC[ENDING]] |Reading sub-clause A sub-clause following - -|RETURN or WITH |Specifying that the output should be sorted in either ascending (the default) or descending order. - -|RETURN … [AS] |Projecting Defines what to include in the query result set. - -|SKIP |Reading/Writing A sub-clause defining from which record to start including the records in the output. - -|WITH … [AS] |Projecting Allows query parts to be chained together, piping the results from one to be used as starting points or criteria in the next. - -See below for restrictions. - -|WHERE |Reading sub-clause A sub-clause used to add constraints to the patterns in a MATCH clause, or to filter the results of a WITH clause. -|=== - -=== Operators -[cols="1,1"] -|=== -|% |Mathematical Modulo division - -|* |Mathematical Multiplication - -|+ |Mathematical Addition - -|+ |String Concatenation - -|+ |List Concatenation - -|- |Mathematical Subtraction or unary minus - -|. |General Property access - -|/ |Mathematical Division - -|< |Comparison Less than - -|< = |Comparison Less than or equal to - -|<> |Comparison Inequality - -|= |Comparison Equality - -|> |Comparison Greater than - -|>= |Comparison Greater than or equal to - -|AND |Boolean Conjunction - -|CONTAINS |String comparison Case-sensitive inclusion search - -|DISTINCT |General Duplicate removal - -|ENDS WITH |String comparison Case-sensitive suffix search - -|IN List |List element existence check - -|IS NOT NULL |Comparison Non-null check - -|IS NULL |Comparison null check - -|NOT |Boolean Negation - -|OR |Boolean Disjunction - -|STARTS WITH |String comparison Case-sensitive prefix search - -|XOR |Boolean Exclusive disjunction - -|[ ] |General Subscript (dynamic property access) - -|[ ] |List Subscript (accessing element(s) in a list) - -|^ |Mathematical Exponentiation -|=== - -=== Functions - -[cols="1,1"] -|=== -|abs() |Numeric Returns the absolute value of a number. - -|acos() |Trigonometric Returns the arccosine of a number in radians. - -|asin() |Trigonometric Returns the arcsine of a number in radians. - -|atan() |Trigonometric Returns the arctangent of a number in radians. - -|atan2() |Trigonometric Returns the arctangent2 of a set of coordinates in radians. - -|avg() |Aggregating Returns the average of a set of numeric values. - -|ceil() |Numeric Returns the smallest floating point number that is greater than or equal to a number and equal to a mathematical integer. - -|cos() |Trigonometric Returns the cosine of a number. - -|cot() |Trigonometric Returns the cotangent of a number. - -|count() |Aggregating Returns the number of values or records. - -|degrees() |Trigonometric Converts radians to degrees. - -|e() |Logarithmic Returns the base of the natural logarithm, e. - -|elementId() |Scalar Returns the String id of a relationship or node. - -|exp() |Logarithmic Returns e^n, where e is the base of the natural logarithm, and n is the value of the argument expression. - -|floor() |Numeric Returns the largest floating point number that is less than or equal to a number and equal to a mathematical integer. - -|head() |Scalar Returns the first element in a list. - -|id() |Scalar Returns the id of a relationship or node. - -|last() |Scalar Returns the last element in a list. - -|left() |String Returns a string containing the specified number of leftmost characters of the original string. - -|log() |Logarithmic Returns the natural logarithm of a number. - -|log10() |Logarithmic Returns the common logarithm (base 10) of a number. - -|lTrim() |String Returns the original string with leading whitespace removed. - -|max() |Aggregating Returns the maximum value in a set of values. - -|min() |Aggregating Returns the minimum value in a set of values. - -|pi() |Trigonometric Returns the mathematical constant pi. - -|radians() |Trigonometric Converts degrees to radians. - -|rand() |Numeric Returns a random floating point number in the range from 0 (inclusive) to 1 (exclusive); i.e. [0, 1). - -|range() |List Returns a list comprising all integer values within a specified range. - -|replace() |String Returns a string in which all occurrences of a specified string in the original string have been replaced by another (specified) string. - -|reverse() |String Returns a string in which the order of all characters in the original string have been reversed. - -|right() |String Returns a string containing the specified number of rightmost characters of the original string. - -|round() |Numeric Returns the value of a number rounded to the nearest integer. - -|rTrim() |String Returns the original string with trailing whitespace removed. - -|sign() |Numeric Returns the signum of a number: 0 if the number is 0, -1 for any negative number, and 1 for any positive number. - -|sin() |Trigonometric Returns the sine of a number. - -|size() |Scalar Returns the number of items in a list. (When applied to a list) - -|split() |String Returns a list of strings resulting from the splitting of the original string around matches of the given delimiter. - -|sqrt() |Logarithmic Returns the square root of a number. - -|stDev() |Aggregating Returns the standard deviation for the given value over a group for a sample of a population. - -|stDevP() |Aggregating Returns the standard deviation for the given value over a group for an entire population - -|substring() |String Returns a substring of the original string, beginning with a 0-based index start and length. - -|sum() |Aggregating Returns the sum of a set of numeric values. - -|tail() |List Returns all but the first element in a list. - -|tan() |Trigonometric Returns the tangent of a number. - -|timestamp() |Scalar Returns the difference, measured in milliseconds, between the current time and midnight, January 1, 1970 UTC. - -|toLower() |String Returns the original string in lowercase. - -|toString() |String Converts an integer, float or boolean value to a string. - -|toUpper() |String Returns the original string in uppercase. - -|trim() |String Returns the original string with leading and trailing whitespace removed. - -|toBoolean() |Scalar Converts a string value to a boolean value. - -|toFloat() |Scalar Converts an integer or string value to a floating point number. - -|toInteger() |Scalar Converts a floating point or string value to an integer value. - -|=== - -=== Expressions -[cols="1,1"] -|=== -|CASE Expression |A generic conditional expression, similar to if/else statements available in other languages. -|=== - -== openCypher Features Not Yet Supported -=== Clauses -[cols="1,1] -|=== -|OPTIONAL MATCH |Reading Specify the patterns to search for in the database while using nulls for missing parts of the pattern. - -|CALL […YIELD] |Reading/Writing Invoke a procedure deployed in the database. - -|CREATE |Writing create nodes and relationships. - -|MERGE |Reading/Writing Ensures that a pattern exists in the graph. Either the pattern already exists, or it needs to be created. - -|REMOVE |Writing Remove properties and labels from nodes and relationships. - -|UNION |Set operations Combines the result of multiple queries. Duplicates are removed. - -|UNION ALL |Set operations Combines the result of multiple queries. Duplicates are retained. - -|UNWIND … [AS] |Projecting Expands a list into a sequence of records. - -|SET |Writing Update labels on nodes and properties on nodes and relationships. -|=== - -=== Operators -N/A - -=== Functions -[cols="1,1"] -|=== -|coalesce() |Scalar Returns the first non-null value in a list of expressions. - -|collect() |Aggregating Returns a list containing the values returned by an expression. - -|endNode() |Scalar Returns the end node of a relationship. - -|exists() |Predicate Returns true if a match for the pattern exists in the graph, or if the specified property exists in the node, relationship or map. - -|keys() |List Returns a list containing the string representations for all the property names of a node, relationship, or map. - -|labels() |List Returns a list containing the string representations for all the labels of a node. - -|length() |Scalar Returns the length of a path. - -|nodes() |List Returns a list containing all the nodes in a path. - -|percentileCont() |Aggregating Returns the percentile of the given value over a group using linear interpolation. - -|percentileDisc() |Aggregating Returns the percentile of the given value over a group using a rounding method. - -|properties() |Scalar Returns a map containing all the properties of a node or relationship. - -|relationships() |List Returns a list containing all the relationships in a path. - -|reverse() |List Returns a list in which the order of all elements in the original list have been reversed. - -|size() |Scalar Returns the number of subgraphs matching the pattern expression. (When applied to -pattern expression) - -|size() |Scalar Returns the size of a string. (When applied to string) - -|startNode() |Scalar Returns the start node of a relationship. - -|type() |Scalar Returns the string representation of the relationship type. - -|=== - -=== Syntax - -Certain openCypher syntax is also *not* supported. - -* Queries with a *WITH* clause that *does not* implicitly group by exactly one vertex variable. - -. 0 vertex variables as group key -[source,gsql] -MATCH (u:User {name: "John"}) // find all users with the same friend count as John -WITH u.friendCount AS fc // note, u not included in group key list -MATCH (o:User {friendCount: fc}) -… - -. More than 1 vertex variables as group key -[source,gsql] -MATCH (u1) -[:communication]- (x) -[:communication]- (u2) -WITH u1, u2, COUNT(x) // we support only u1 or only u2 in list -… - -* Queries introducing path variables -[source,gsql] -MATCH p = (u1) -[e1:communication]- (x) -[e2:communication]- (u2) // p is path var -… - -* Queries whose *MATCH* pattern *does not* include at least one vertex variable from immediately preceding *WITH* clause. -[source,gsql] -MATCH (u:user) -[:communication]- (o) -WITH u, … -MATCH (x) -[:communication]-(y) // this pattern must refer to u -… - -* Queries with disconnected *MATCH* pattern fragments -[source,gsql] -MATCH (x:user), (y:user) -WHERE x.friendCount = y.friendCount -… - -* Pattern fragments (x:user) and (y:user) *are not* connected by edge traversal or by sharing vertex variables. - diff --git a/modules/querying/nav.adoc b/modules/querying/nav.adoc index 31d4ace2..2b3b1081 100644 --- a/modules/querying/nav.adoc +++ b/modules/querying/nav.adoc @@ -1,12 +1,14 @@ -* xref:index.adoc[Querying] -** xref:syntax-versions.adoc[] -** xref:query-operations.adoc[] -** xref:query-optimizer/index.adoc[] -*** xref:query-optimizer/enable-cost-optimizer.adoc[] -*** xref:query-optimizer/stats-api.adoc[] +* xref:query-modes.adoc[] +* xref:query-operations.adoc[Create and Run Queries] ** xref:distributed-query-mode.adoc[] +* xref:index.adoc[GSQL Language] +** xref:syntax-versions.adoc[] + ** xref:data-types.adoc[] ** xref:accumulators.adoc[] +** xref:select-statement/index.adoc[] +*** xref:select-statement/select-statement-v1.adoc[] +*** xref:select-statement/sql-like-select-statement.adoc[] ** xref:operators-and-expressions.adoc[] ** xref:func/index.adoc[] *** xref:func/aggregation-functions.adoc[] @@ -24,13 +26,17 @@ *** xref:func/vector-functions.adoc[] *** xref:func/vertex-methods.adoc[] ** xref:declaration-and-assignment-statements.adoc[] -** xref:select-statement/index.adoc[] -*** xref:select-statement/select-statement-v1.adoc[] -*** xref:select-statement/sql-like-select-statement.adoc[] -** xref:control-flow-statements.adoc[] -** xref:data-modification-statements.adoc[] -** xref:output-statements-and-file-objects.adoc[] + +** xref:control-flow-statements.adoc[Control Flow] +** xref:data-modification-statements.adoc[Updating Data] +** xref:output-statements-and-file-objects.adoc[Writing Output] +*** xref:write-output-to-cloud.adoc[Write Output to Cloud] ** xref:exception-statements.adoc[] ** xref:comments.adoc[] -** xref:write-query-data-to-cloud.adoc[] +* Profile and Optimize +** xref:query-optimizer/query-plan-cache.adoc[] +** xref:query-optimizer/query-profiling.adoc[] +** xref:query-optimizer/index.adoc[] +*** xref:query-optimizer/enable-cost-optimizer.adoc[Enable Query Optimizer] +*** xref:query-optimizer/stats-api.adoc[] diff --git a/modules/querying/pages/accumulators.adoc b/modules/querying/pages/accumulators.adoc index 2c7699ac..06017987 100644 --- a/modules/querying/pages/accumulators.adoc +++ b/modules/querying/pages/accumulators.adoc @@ -652,65 +652,105 @@ include::appendix:example$minimal_net/accum_oraccum_results.json[] [#_bitwiseandaccum_bitwiseoraccum] === BitwiseAndAccum / BitwiseOrAccum -The BitwiseAndAccum and BitwiseOrAccum types calculate and store the cumulative result of a series of bitwise boolean operations and store the resulting bit sequences. -The default length for both BitwiseAndAccum and BitwiseOrAccum is 64 bit. -You can specify the length of both types by appending the desired length in angle brackets``<>``. +The BitwiseAndAccum and BitwiseOrAccum types represent fixed-length or dynamic-length bit sequences. They calculate the cumulative result of bitwise boolean operations and store the resulting sequences. - -Fundamental to understanding and using bitwise operations is the knowledge that integers are stored in base-2 representation as a 64-bit sequence of 1s and 0s. -"Bitwise" means that each bit is treated as a separate boolean value, with 1 representing true and 0 representing false. -Hence, an integer is equivalent to a sequence of boolean values. +Integers are stored as sequences of 1s and 0s (bits) in base-2, with each bit acting as a boolean value (1 for true, 0 for false). Computing the Bitwise `AND` of two numbers A and B means computing the bit sequence C where the stem:[j_{th}] bit of C, denoted stem:[C_j], is equal to stem:[A_j] `AND` stem:[B_j]. ==== Declaration -A bitwise accumulator has different declaration syntax depending on its length: +Declare bitwise accumulators as regular fixed-length (up to 64 bits), long fixed-length (over 64 bits), or dynamic-length (new in version 4.2.1) based on your query’s needs. + +* *Regular Fixed-Length (Up to 64 Bits)*: Stored in a single 64-bit integer, ignoring overflow. Declare without a length (defaults to 64 bits) or with a length of 64 or less. ++ +[,gsql] +---- +BitwiseOrAccum @@bw1; // Default 64 bits +BitwiseAndAccum<64> @@bw2; +BitwiseOrAccum<32> @@bw3; +---- + +* *Long Fixed-Length (Over 64 Bits)*: Stored in an array of integers, with the rightmost integer holding the 64 least significant bits, ignoring overflow. Use .clear() to free memory during queries. ++ +[,gsql] +---- +BitwiseOrAccum<65> @@bw4; +BitwiseAndAccum<100> @@bw5; +---- + +* *Dynamic-Length*: Set the length at runtime using query parameters or variables (new in version 4.2.1). Use .clear() to free memory. You cannot change the length after declaration (e.g., .resize() is not supported). ++ +[,gsql] +---- +CREATE QUERY test(UINT len) { + INT length = len * 10; + BitwiseOrAccum @@bw6; + BitwiseOrAccum @@bw7; +} +---- + +For lengths over 64 bits, the system uses an array. +For example, an 80-bit BitwiseAndAccum like `@@bit80<80> = [123, 456]` concatenates the bit sequences, with 456 covering the 64 least significant bits and 123 the rest, ignoring overflow. -* When a bitwise accumulator length is less than or equal to 64 bit, it's assigned using one integer. -The integer is converted to a 64-bit sequence of 1s and 0s. -Overflow on the left is ignored. -* When a bitwise accumulator length is longer than 64 bit, it's assigned using an array of two integers. -Each integer is converted to a 64-bit sequence of 1s and 0s. -The integer in the second position will take up the first 64 bits from the right of the sequence, and the integer on the left will take up the remaining bits. -Any overflowing bits will be ignored. +==== Accumulation behavior -For example, if you are declaring an 80-bit BitwiseAndAccum: +For BitwiseAndAccum, `+= arg` updates the accumulator's state to be the Bitwise `AND` of the current state and `arg`. +BitwiseOrAccum behaves the same, with the exception that it computes a Bitwise `OR`. - @@bit80<80> = [123, 456] +==== Bitwise Comparison and Logic Operators -456 represents the 64-bit sequence `0000….000111001000` (zeros omitted), and 123 represents the 64-bit sequence `0000000000…00001111011` (zeros omitted). +Because bitwise accumulators have values that are akin to binary integers, they support both comparison operators: -When the two integers are joined together, the 64-bit sequence on the right (456) takes up the 64 bits from the right. -The 64-bit sequence on the left (123) takes up the remaining 16 bits and the overflow on the left is ignored. +`<`, `>`, `>=`, `\<=`, `==`,`!=` -The resulting BitwiseAndAccum prints as below: +Examples: Assume AccumA and AccumB are 8-bit accumulators with the following values: - 0000000001111011 (16bits in total) 0000000...000111001000 (64bits in total) +[source] +---- +AccumA = 00010001; // decimal 17 +AccumB = 00010000; // decimal 16 +AccumA == 17 // true +AccumA > AccumB // true +AccumA < AccumB // false +---- +Bitwise boolean logic operators require accumulators of the same type and length, producing a new accumulator of the same type and length. -==== Accumulation behavior +.Bitwise logic operators +[cols="1,2"] +|=== +|Operator |Description -For BitwiseAndAccum, `+= arg` updates the accumulator's state to be the Bitwise `AND` of the current state and `arg`. -BitwiseOrAccum behaves the same, with the exception that it computes a Bitwise `OR`. +|` & ` +|Returns a new bitwise accumulator where each bit is the Boolean `AND` of the corresponding bits in `accum1` and `accum2`. + +|` \| ` +|Returns a new bitwise accumulator where each bit is the Boolean `OR` of the corresponding bits in `accum1` and `accum2`. + +|` ^ ` +|Returns a new bitwise accumulator where each bit is the Boolean `XOR` (exclusive OR) of the corresponding bits in `accum1` and `accum2`. + +|`~ ` +|Returns a new bitwise accumulator where each bit is the Boolean `NOT` of the corresponding bit in `accum`. +|=== [CAUTION] ==== -Bitwise Operations and Negative Integers - -Most computer systems represent negative integers using "2's complement" format, where the uppermost bit has special significance. Operations that affect the uppermost bit are crossing the boundary between positive and negative numbers, and vice versa. +Bitwise operations on negative integers use 2’s complement, where the uppermost bit indicates the sign, which may affect results. ==== -==== Functions -This is a list of methods of BitwiseAndAccum and BitwiseOrAccum. -If a method returns an `BitwiseAndAccum` or `BitwiseOrAccum`, it returns the same type as the instance that calls the method. +[discrete] +==== *Functions* + +BitwiseAndAccum and BitwiseOrAccum support these functions. Mutator functions, which modify the accumulator, cannot be used in PRINT statements. .Bitwise accumulator functions |=== |Function |Return type |Accessor/Mutator |Description |`.reset()` -|None. +|`VOID` |Mutator |Sets all bits to 0. @@ -728,12 +768,12 @@ a|Returns the 1 or 0 at the provided index. The position of the bit value to return. |`.set( )` -|None. +|`VOID` |Mutator |Sets all bits to 1. |`.set( index, value )` -|None. +|`VOID` |Mutator a|Sets the bit at the provided index to the desire value. @@ -744,36 +784,40 @@ a|Sets the bit at the provided index to the desire value. The value of the bit. |`.flip( index )` -|None. +|`VOID` |Mutator |Flips the bit at the specified index. If the bit is 0, changes it to 1 and vice versa. |`.flip( fromIndex [, toIndex ] )` -|None. +|`VOID` |Mutator |Flips the bits in the specified range. |`.xor ( accum )` -|None. +|`VOID` |Mutator |Compares two bitwise accumulators of the same length. Returns a Bitwise accumulator whose every bit is the exclusive `OR` result between the two bitwise accumulators. |`.and ( accum )` -|None. +|`VOID` |Mutator |Compares two bitwise accumulators of the same length. Returns a bitwise accumulator whose every bit is the `AND` result between the two bitwise accumulators. |`.or ( accum )` -|None. +|`VOID` |Mutator |Compares two bitwise accumulators of the same length. Returns a Bitwise accumulator whose every bit is the `OR` result between the two bitwise accumulators. -|=== +|`.clear()` +|`VOID` +|Mutator +|Frees memory for long and dynamic-length accumulators. +|=== ==== Example @@ -828,6 +872,7 @@ Functions that modify the ListAccum (mutator functions) can be used only under t * Mutator functions of global accumulators may only be used at the query-body level. * Mutator functions of vertex-attached accumulators may only be used in a `POST-ACCUM` clause. +* Mutator functions may not be used in a PRINT statement. ==== |=== @@ -965,6 +1010,7 @@ Functions that modify the SetAccum (mutator functions) can be used only under th * Mutator functions of global accumulators may only be used at the query-body level. * Mutator functions of vertex-attached accumulators may only be used in a `POST-ACCUM` clause. +* Mutator functions may not be used in a PRINT statement. ==== |=== @@ -1084,6 +1130,7 @@ Functions which modify the BagAccum (mutator functions) can be used only under t * Mutator functions of global accumulators may only be used at the query-body level. * Mutator functions of vertex-attached accumulators may only be used in a `POST-ACCUM` clause. +* Mutator functions may not be used in a PRINT statement. ==== |=== @@ -1176,6 +1223,7 @@ Functions that modify the MapAccum (mutator functions) can be used only under th * Mutator functions of global accumulators may only be used at the query-body level. * Mutator functions of vertex-attached accumulators may only be used in a `POST-ACCUM` clause. +* Mutator functions may not be used in a PRINT statement. ==== |=== @@ -1304,6 +1352,7 @@ Functions that modify the ArrayAccum (mutator functions) can be used only under * Mutator functions of global accumulators may only be used at the query-body level. * Mutator functions of vertex-attached accumulators may only be used in a `POST-ACCUM` clause. +* Mutator functions may not be used in a PRINT statement. ==== |=== @@ -1433,6 +1482,7 @@ Functions that modify the `HeapAccum` (mutator functions) can be used only under * Mutator functions of global accumulators may only be used at the query-body level. * Mutator functions of vertex-attached accumulators may only be used in a `POST-ACCUM` clause. +* Mutator functions may not be used in a PRINT statement. ==== |=== @@ -1503,6 +1553,14 @@ GroupByAccum In the EBNF above, the *type* terms form the key set, and the *accumType* terms form the map's value. Since they are accumulators, they perform a grouping. Like a MapAccum, if we try to store a (key->value) whose key has already been used, then the new value will accumulate to the data which is already stored. In this case, each field of the multiple-field value has its own accumulation function. One way to think about GroupByAccum is that each unique key is a group ID. + +[NOTE] +==== +Operations between different GroupByAccums with the same data types but different field names are not supported. +They will result in a Type Check Error during `CREATE QUERY`. +In earlier versions, such queries would fail with a compilation error during query installation. +==== + In GroupByAccum, the key types can be base type or tuple. The accumulators are used for aggregating group values. Each accumulator type can be any type including HeapAccum. Each base type and each accumulator type must be followed an alias. Below is an example declaration. [source,gsql] @@ -1525,6 +1583,7 @@ Functions that modify the GroupByAccum (mutator functions) can be used only unde * Mutator functions of global accumulators may only be used at the query-body level. * Mutator functions of vertex-attached accumulators may only be used in a `POST-ACCUM` clause. +* Mutator functions may not be used in a PRINT statement. ==== |=== diff --git a/modules/querying/pages/control-flow-statements.adoc b/modules/querying/pages/control-flow-statements.adoc index 708451bf..585c1bf4 100644 --- a/modules/querying/pages/control-flow-statements.adoc +++ b/modules/querying/pages/control-flow-statements.adoc @@ -2,7 +2,9 @@ :description: Reference for control flow statements in the GSQL query language. :stem: latexmath -The GSQL Query Language includes a comprehensive set of control flow statements to empower sophisticated graph traversal and data computation: `IF/ELSE`, `CASE`, `WHILE`, and `FOREACH`. +The GSQL Query Language includes a comprehensive set of control flow statements to empower sophisticated graph traversal and data computation with _conditional_ (`IF/ELSE`, `CASE`) and _iterative_ (`WHILE`, and `FOREACH`) execution. + +You may also be interested in xref:operators-and-expressions.adoc#_case_expressions[CASE expressions]. [#_differences_in_block_syntax] == Differences in Block Syntax diff --git a/modules/querying/pages/create-and-install-queries.adoc b/modules/querying/pages/create-and-install-queries.adoc new file mode 100644 index 00000000..bc7a88bf --- /dev/null +++ b/modules/querying/pages/create-and-install-queries.adoc @@ -0,0 +1,524 @@ += Create and Install Queries +:navtitle: CREATE/INSTALL QUERY +:description: the CREATE QUERY and INSTALL QUERY commands in GSQL, key stages for developing optimized TigerGraph queries. +:toc: + +This page describes the <<#_create_query>> and <<#_install_query>> commands, the steps that precede running an installed (compiled) procedural query. +See + +[#_create_query] +== CREATE QUERY + +Define and store a procedural query in the catalog for future use. +The syntax of the query is checked but it is not compiled. + +=== Required privilege + +`CREATE_QUERY` or `UPDATE_QUERY` + +* To create a new query, `CREATE_QUERY` privilege is needed. +* To replace (update) a query, `UPDATE_QUERY` privilege is needed. + +=== Basic Syntax and Example + +[source,ebnf] +.Basic Syntax, with only the most common options +---- +createQuery := CREATE [OR REPLACE] [DISTRIBUTED] [OPENCYPHER] queryName + "(" [parameterList] ")" + [FOR GRAPH graphName] + "{" queryBody "}" + +queryBody := [declStmts] queryBodyStmts +---- + +[,gsql] +.Example +---- +CREATE OR REPLACE DISTRIBUTE QUERY listTopBooks <1> + (INT k = 10) <2> +{ + AvgAccum @avg_rating; <3> + + books = SELECT b <4> + FROM (u:User) -[r:User_Book_Rating]- (b:Book) + ACCUM b.@avg_rating := r.rating + ORDER BY b.@avg_rating DESC + LIMIT k; + PRINT books; +} +---- + +<1> The `queryName` is `listTopBooks`. +<2> The `[parameterList]` is a single parameter with a default value of 10. +<3> There is one `declStmt` : a local accumulator AvgAccum to compute average ratings of books. +<4> The `queryBodyStmts` has one `SELECT` and one `PRINT` statement. + + +=== Full Syntax and Options +[source,ebnf] +.Full syntax for CREATE QUERY +---- +createQuery := CREATE [OR REPLACE] [TEMPLATE | DISTRIBUTED] QUERY + [packageName["."packageName].]queryName + "(" [parameterList] ")" + [FOR GRAPH graphName] + [RETURNS "(" baseType | accumType ")"] + [API "(" apiName ")"] + [SYNTAX syntaxName] + "{" queryBody "}" + +queryBody := [typedefs] [declExceptStmts] queryBodyStmts +---- + + + +=== Key Parts of CREATE QUERY + +`OR REPLACE`:: + +If the optional keywords `OR REPLACE` are included, then this query definition, if error-free, replaces a previous definition with the same query name. +If the original query was installed, you'll need to reinstall the new query. ++ +However, if there are any errors in this query definition, then the previous query definition is maintained. +If the `OR REPLACE` option is not used, GSQL rejects a `CREATE QUERY` command that uses an existing name. +`DISTRIBUTED`:: +The `DISTRIBUTED` option applies only to installations where the graph has been distributed across a cluster. +If specified, the query will run with a different execution model which may give better performance for queries that traverse a large portion of the cluster. +For details, see xref:distributed-query-mode.adoc[Distributed Query Mode.] + +`queryName`:: Name of the query. + +`parameterList`:: A list of parameters for the query. +The parameter list for a query follows the following form: ++ +[source,ebnf] +---- +parameterType paramName ["=" constant] ["," parameterType paramName ["=" constant]]* +---- +For a list of allowed data types for query parameters, see xref:data-types.adoc#_query_parameter_types[Query parameter types]. + +`FOR GRAPH graphName`:: Specifies the graph that the query is created on. +This clause is optional if you have already specified a working graph either when entering GSQL or through the `USE GRAPH` command. + +`RETURNS` clause:: +The optional `RETURNS` clause makes the query a subquery and specifies the data type to be returned in the `RETURN` statement of the subquery. +For more information, see xref:operators-and-expressions.adoc#_subqueries[Subqueries]. + +`API v2`:: Specifies the JSON output format. +The only option is v2. + +`SYNTAX syntaxName`:: Specifies the GSQL syntax version to be used by the query. +See the +xref:querying:syntax-versions.adoc[] for an outline of the differences. +See +xref:tutorials:pattern-matching/index.adoc[Pattern Matching tutorial] for +details on v2. + +`queryBody`:: +The query body contains a sequence of data retrieval-and-computation statements. ++ +Typedefs allow the definition of custom types for use within the body. +The declarations support the definition of _accumulators_ (see Chapter "xref:accumulators.adoc[Accumulators]" for more details) and global/local variables. +All accumulators and global variables must be declared before any statements.There are various types of statements that can be used within the body. ++ +Typically, the core statement(s) in the body of a query is one or more `SELECT`, `UPDATE`, `INSERT`, `DELETE` statements. +The language supports conditional statements such as an `IF` statement as well as looping constructs such as `WHILE` and `FOREACH`. +It also supports calling functions, assigning variables, printing, and modifying the graph data. ++ +The query body may include calls to other queries. That is, the other queries are treated as subquery functions. +See the subsection on "xref:querying:operators-and-expressions.adoc#_subqueries[subqueries]". ++ +Additionally, GSQL supports openCypher syntax in the query body. See pages xref:openCypher-in-gsql:openCypher-in-gsql.adoc[], xref:openCypher-in-gsql:openCypher-in-gsql-web-shell.adoc[], and xref:openCypher-in-gsql:openCypher-gsql-from-clause-extension.adoc[] to learn more about openCypher and for examples. + +=== Examples + +.Example of a `CREATE QUERY` statement +[source.wrap,gsql] +---- +include::appendix:example$social_net/query_operations_example_create_query.gsql[] +---- + +=== Default query parameter values + +You can specify default values for parameters of primitive types when creating a query. Primitive types include: + +* `INT` +* `UINT` +* `FLOAT` +* `DOUBLE` +* `STRING` +* `BOOL` +* `DATETIME` + +To specify the default value for a parameter, use the assignment operator (`=`) after the parameter name and specify the default value: + +.Example of a `CREATE QUERY` command with a default parameter value +[source.wrap,gsql] +---- +include::appendix:example$social_net/query_operations_example_create_query_defaults.gsql[] +---- + +To specify the default value of a `DATETIME` type parameter, use the `to_datetime()` function. +You cannot use other functions that return a `DATETIME` value to specify the default value. +For example, the following query definition sets the default value of `d1` to `2023-01-01 00:00:00`. + +[.wrap,gsql] +---- +CREATE QUERY print_default(DATETIME d1 = to_datetime("2023-01-01 00:00:00")) { + PRINT d1; +} +---- + + + +[#_dynamic_querying] +=== Dynamic querying + +TigerGraph 3.0+ supports Dynamic Querying. +This means the query can be written and installed as a saved procedure without referencing a particular graph. +Schema details -- the name of the graph, vertex types, edge types, and attributes -- can all be parameterized and only need to be specified at run time. + +Here are the ingredients for a dynamic query: + +* *Graph name:* When xref:querying:query-operations.adoc#_create_query[creating a query], *`FOR GRAPH graphName`* is optional, as long as the graph has been specified already. +The graph name can be specified either when entering GSQL: *`GSQL -g graphName []`* or once inside the GSQL shell, by using the *`USE GRAPH graphName`* command. +* *Vertex type and edge type in `SELECT` statements*. +Typically, the xref:querying:select-statement/index.adoc#_from_clause[`FROM` clause] mentions the name of specific vertex types and edge types. +String or string set parameters can be used for edge and target types instead. +* *Attribute names*. +The xref:querying:func/vertex-methods.adoc[`getAttr` and `setAttr` functions], which take attribute name and data type as string parameters, can be used to parameterize attribute access. +* `INSERT` *statements*: If you are using xref:querying:data-modification-statements.adoc#_insert_into_statement[`INSERT`] to add data to your graph, you need to specify what type of vertex or edge you want to add.This can also be parameterized. + +The following example demonstrates Dynamic GSQL Query techniques using the xref:graph-ml:centrality-algorithms:pagerank.adoc[PageRank algorithm] from our Graph Data Science library. +The query is written with schema information embedded statically in it: + +* graph name = social +* vertex type = Page +* edge type = Link +* vertex attribute = Score + +[tabs] +==== +Embedded schema:: ++ +-- +[source,gsql] +---- +include::appendix:example$test-schema/query_operations_embedded_schema.gsql[] +---- +-- +Dynamic querying:: ++ +-- +[source,gsql] +---- +include::appendix:example$test-schema/query_operations_dynamic_querying.gsql[] +---- +-- +==== + + + +=== Draft queries + +GSQL internally has two statuses for queries, `DRAFT` and `VALID`. + +If your query passes the semantic checks upon running the `CREATE QUERY` command, it is saved automatically in `VALID` status. +If not, along with the error statement, a message appears to indicate the draft status. + +In this example, the first query gets saved upon running `CREATE QUERY`, while the second one remains a draft. + +[source, gsql] +---- +GSQL > CREATE QUERY valid_query(){ print 1; } +Successfully created queries: [valid_query]. + + +GSQL > BEGIN +GSQL > CREATE QUERY draft_query(){ +GSQL > PRINT; +GSQL > PRINT "I am a draft" +GSQL > } +GSQL > END +line 2:7 mismatched input ';' expecting {ABORT, AND, ANY, AVG, BY, COALESCE, COMMIT, COUNT, DATETIME_ADD, DATETIME_SUB, DISTINCT, FALSE, FILE, GROUP, INSERT, ISEMPTY, LASTHOP, LIST, LOG, MAP, MATCH, MAX, MIN, NOT, NOW, OR, PATH, PER, RANGE, REPLACE, SELECT_VERTEX, SET, SRC, SUM, TGT, TO_DATETIME, TRIM, TRUE, UPDATE, GSQL_INT_MAX, GSQL_INT_MIN, GSQL_UINT_MAX, '__ENGINE__E_ATTR', '__ENGINE__SRC_ATTR', '__ENGINE__TGT_ATTR', '__ENGINE__V_ATTR', '__ENGINE__SRC_VAL', '__ENGINE__TGT_VAL', '__ENGINE__V_VAL', '__ENGINE__MESSAGE', '__ENGINE__CONTEXT', '__ENGINE__REQUEST', '__ENGINE__SERVICEAPI', '(', '[', '-', '.', '_', CONST_INT, CONST_STR, NAME, GACCNAME} +line 4:0 mismatched input '}' expecting {TO_CSV, WHERE, ',', ';'} +Parsing encountered 2 syntax error(s) + +Saved as draft query with type/semantic error: [draft_query]. +---- + +Because the query status is determined and saved internally, there are no commands for users to choose to save valid queries as `DRAFT` status. + +Queries are not saved as drafts in the following situations: + +* The user does not have the correct permissions to create a query. +* An existing valid query has the same name, and there is no `REPLACE` command used while creating the new query. +* An existing valid query is called by another query. +** The new query will change its signature (parameters or return type). +* A circular call is detected, where `queryA` calls `queryB and `queryB` calls `queryA`. +** However, a recursive call (A calls A) is allowed. + +If a query is saved as a draft before it reaches valid status, any queries that call it are also set to draft status. + +[NOTE] +==== +If a user creates a query, this user becomes the owner of this query automatically. + +For a detailed description, please refer to xref:{page-component-version}@tigergraph-server:user-access:fine-grained-query-privileges.adoc +==== + +[#_statement_types] +== Statement types + +A _statement_ is a standalone instruction that expresses an action to be carried out. +The most common statements are _data manipulation language (DML) statements_. +DML statements include the `SELECT`, `UPDATE`, `INSERT INTO`, `DELETE FROM`, and `DELETE` statements. + +A GSQL query has two levels of statements. +The upper-level statement type is called _query-body-level statement_, or _*query-body statement*_ for short. +This statement type is part of either the top-level block or a query-body control flow block. +For example, each of the statements at the top level directly under `CREATE QUERY` is a query-body statement. +If one of the statements is a `CASE` statement with several `THEN` blocks, each of the statements in the `THEN` blocks is also a query-body statement. +Each query-body statement ends with a semicolon. + +The lower-level statement type is called _DML-sub-level statement_ or _DML-sub statement_ for short. +This statement type is used inside certain query-body DML statements, to define particular data manipulation actions.DML-sub-statements are comma-separated. +There is no comma or semicolon after the last DML-sub-statement in a block. +For example, one of the top-level statements is a `SELECT` statement, each of the statements in its `ACCUM` clause is a DML-sub-statement. +If one of those DML-sub-statements is a `CASE` statement, each of the statement in the `THEN` blocks is a DML-sub-statement. + +There is some overlap in the types. +For example, an assignment statement can be used either at the query-body level or the DML-sub-level. + +[source,ebnf] +---- +queryBodyStmts := (queryBodyStmt ";")+ + +queryBodyStmt := assignStmt // Assignment + | vSetVarDeclStmt // Declaration + | gAccumAssignStmt // Assignment + | gAccumAccumStmt // Assignment + | lAccumAccumStmt // Assignment + | funcCallStmt // Function Call + | selectStmt // Select + | queryBodyCaseStmt // Control Flow + | queryBodyIfStmt // Control Flow + | queryBodyWhileStmt // Control Flow + | queryBodyForEachStmt // Control Flow + | BREAK // Control Flow + | CONTINUE // Control Flow + | updateStmt // Data Modification + | insertStmt // Data Modification + | queryBodyDeleteStmt // Data Modification + | printStmt // Output + | printlnStmt // Output + | logStmt // Output + | returnStmt // Output + | raiseStmt // Exception + | tryStmt // Exception + +DMLSubStmtList := DMLSubStmt ["," DMLSubStmt]* + +DMLSubStmt := assignStmt // Assignment + | funcCallStmt // Function Call + | gAccumAccumStmt // Assignment + | lAccumAccumStmt // Assignment + | attrAccumStmt // Assignment + | vAccumFuncCall // Function Call + | localVarDeclStmt // Declaration + | DMLSubCaseStmt // Control Flow + | DMLSubIfStmt // Control Flow + | DMLSubWhileStmt // Control Flow + | DMLSubForEachStmt // Control Flow + | BREAK // Control Flow + | CONTINUE // Control Flow + | insertStmt // Data Modification + | DMLSubDeleteStmt // Data Modification + | printlnStmt // Output + | logStmt // Output +---- + +Guidelines for understanding statement type hierarchy: + +* Top-level statements are Query-Body type (each statement ending with a semicolon). +* The statements within a DML statement are DML-sub statements (comma-separated list). +* The blocks within a Control Flow statement have the same type as the entire Control Flow statement itself. + +// Each statement's operation type is either ControlFlow, DML, or other. +// Each statement's syntax type is either queryBodyStmt or DMLSubStmt. + +.Schematic illustration of relationship between queryBodyStmt and DMLSubStmt +[source,gsql] +---- +CREATE QUERY stmt_types (parameterList) FOR GRAPH g [ + other queryBodyStmt1; + ControlFlow queryBodyStmt2 // ControlFlow inside top level. + other queryBodyStmt2.1; // subStmts in ControlFlow are queryBody unless inside DML. + ControlFlow queryBodyStmt2.2 // ControlFlow inside ControlFlow inside top level + other queryBodyStmt2.2.1; + other queryBodyStmt2.2.2; + END; + DML queryBodyStmt2.3 // DML inside ControlFlow inside top-level + other DMLSubStmt2.3.1, // switch to DMLSubStmt + other DMLSubStmt2.3.2 + ; + END; + DML queryBodyStmt3 // DML inside top level. + other DMLSubStmt3.1, // All subStmts in DML must be DMLSubStmt type + ControlFlow DMLSubStmt3.2 // ControlFlow inside DML inside top level + other DMLSubStmt3.2.1, + other DMLSubStmt3.2.2 + , + DML DMLsubStmt3.3 + other DMLSubStmt3.3.1, + other DMLSubStmt3.3.2 + ; + other queryBodyStmt4; +---- + +Here is a descriptive list of query-body statements: + +|=== +| EBNF term | Common Name | Description + +| assignStmt +| Assignment Statement +| See "Declaration and Assignment Statements" + +| vSetVarDeclStmt +| Vertex Set Variable Declaration Statement +| See "Declaration and Assignment Statements" + +| gAccumAssignStmt +| Global Accumulator Assignment Statement +| See "Declaration and Assignment Statements" + +| gAccumAccumStmt +| Global Accumulator Accumulation Statement +| See "Declaration and Assignment Statements" + +| lAccumAccumStmt +| Local Accumulator Accumulation Statement +| See "Declaration and Assignment Statements" + +| funcCallStmt +| Functional Call or Query Call Statement +| See "Declaration and Assignment Statements" + +| selectStmt +| SELECT Statement +| See "SELECT Statement" + +| queryBodyCaseStmt +| query-body CASE statement +| See "Control Flow Statements" + +| queryBodyIfStmt +| query-body IF statement +| See "Control Flow Statements" + +| queryBodyWhileStmt +| query-body WHILE statement +| See "Control Flow Statements" + +| queryBodyForEachStmt +| query-body FOREACH statement +| See "Control Flow Statements" + +| updateStmt +| UPDATE Statement +| See "Data Modification Statements" + +| insertStmt +| INSERT INTO statement +| See "Data Modification Statements" + +| queryBodyDeleteStmt +| Query-body DELETE Statement +| See "Data Modification Statements" + +| printStmt +| PRINT Statement +| See "Output Statements" + +| logStmt +| LOG Statement +| See Output Statements" + +| returnStmt +| RETURN Statement +| See "Output Statements" + +| raiseStmt +| PRINT Statement +| See "Exception Statements" + +| tryStmt +| TRY Statement +| See "Exception Statements" +|=== + +Here is a descriptive list of DML-sub-statements: + +|=== +| EBNF term | Common Name | Description + +| assignStmt +| Assignment Statement +| See "Declaration and Assignment Statements" + +| funcCallStmt +| Functional Call Statement +| See "Declaration and Assignment Statements" + +| gAccumAccumStmt +| Global Accumulator Accumulation Statement +| See "Declaration and Assignment Statements" + +| lAccumAccumStmt +| Local Accumulator Accumulation Statement +| See "Declaration and Assignment Statements"/ + +| attrAccumStmt +| Attribute Accumulation Statement +| See "Declaration and Assignment Statements" + +| vAccumFuncCall +| Vertex-attached Accumulator Function Call Statement +| See "Declaration and Assignment Statements" + +| localVarDeclStmt +| Local Variable Declaration Statement +| See "SELECT Statement" + +| insertStmt +| INSERT INTO Statement +| See "Control Flow Statements" + +| DMLSubDeleteStmt +| DML-sub DELETE Statement +| See "Data Modification Statements" + +| DMLSubcaseStmt +| DML-sub CASE statement +| See "Data Modification Statements" + +| DMLSubIfStmt +| DML-sub IF statement +| See "Data Modification Statements" + +| DMLSubForEachStmt +| DML-sub FOREACH statement +| See "Data Modification Statements" + +| DMLSubWhileStmt +| DML-sub WHILE statement +| See "Data Modification Statements" + +| logStmt +| LOG Statement +| See "Output Statements" +|=== + +## INSTALL QUERY diff --git a/modules/querying/pages/data-types.adoc b/modules/querying/pages/data-types.adoc index a77c6721..ce381aa5 100644 --- a/modules/querying/pages/data-types.adoc +++ b/modules/querying/pages/data-types.adoc @@ -167,8 +167,9 @@ baseType := INT The default value of each base type is shown in the table below. The default value is the initial value of a base type variable (see Section "Variable Types" for more details), or the default return value for some functions. -The first seven types (`INT`, `UINT`, `FLOAT`, `DOUBLE`, `BOOL`, `STRING`, and `DATETIME`) are the same ones mentioned in the "xref:ddl-and-loading:attribute-data-types.adoc#_primitive_types[Attribute Data Types]" section of xref:ddl-and-loading:system-and-language-basics.adoc[GSQL Language Reference, Part 1]. +The first seven types (`INT`, `UINT`, `FLOAT`, `DOUBLE`, `BOOL`, `STRING`, and `DATETIME`) are the same ones mentioned in the "xref:ddl-and-loading:attribute-data-types.adoc#_primitive_types[Attribute Data Types]" section of xref:ddl-and-loading:attribute-data-types.adoc[GSQL Language Reference, Part 1]. +[cols='2,3,5'] |=== | Type | Default value | Literal @@ -182,7 +183,9 @@ The first seven types (`INT`, `UINT`, `FLOAT`, `DOUBLE`, `BOOL`, `STRING`, and ` | `FLOAT` | `0` -| A decimal precise up to about 7 digits: `3.14159` +a| A decimal precise up to about 7 digits: `3.14159` + +*NOTE*: For large numbers, `DOUBLE` is better. | `DOUBLE` | `0` @@ -221,8 +224,9 @@ The `FLOAT` and `DOUBLE` data types have the same precision limits as in C++. See xref:appendix:common-errors-and-problems.adoc[] for more details. [WARNING] +.Support for fixed and exponential notation ==== -`FLOAT` and `DOUBLE` input values must be in fixed point `d.dddd` __**__format, where `d` is a digit. Output values will be printed in either fixed point for exponential notation, whichever is more compact. +`FLOAT` and `DOUBLE` input values must be in fixed point `d.dddd` format, where `d` is a digit. Output values will be printed in either fixed point or exponential notation, whichever is more compact. The GSQL Loader can read FLOAT and DOUBLE values with exponential notation (e.g., 1.25 E-7). ==== @@ -597,15 +601,15 @@ When the query where the `FILE` was declared finishes running, the `FILE` conten The path should start with `s3://`, followed by the bucket name and the S3 path, e.g., `s3://bucket-name/queryoutput/output.csv`. During the execution of the query, content will be uploaded to the S3 bucket. Note that the S3 object cannot be modified or appended, if an S3 object with the same path already exists, it will be overwritten. ==== Set S3 connection credentials -To use an S3 path, ensure that the necessary permissions and configurations are properly set up to allow read/write access to the specified S3 bucket. Configure the S3 connection credentials using `gadmin config`: -[source,bash] +The S3 credentials can be set as GSQL session parameters, so they persist for a user for a full session. +[source,gsql] ---- -gadmin config set GPE.QueryOutputS3AWSAccessKeyID YOUR_AWS_ACCESS_KEY_ID -gadmin config set GPE.QueryOutputS3AWSSecretAccessKey YOUR_AWS_SECRET_ACCESS_KEY -gadmin config apply -y -gadmin restart gpe -y +set s3_aws_access_key_id = ; +set s3_aws_secret_access_key = ; ---- +These session parameters should be set within the GSQL Editor to enable read/write access to the specified S3 bucket for query results. Replace `` and `` with your actual AWS credentials. + ==== Output Since S3 is a shared storage system, multiple nodes in a cluster can upload to the same S3 bucket. To handle potential conflicts and ensure unique output files, the S3 path can include a suffix based on the instance name, such as `\_GPE_{PartitionId}_{ReplicaId}`. For distributed queries, additional suffixes will be used to differentiate between the manager and worker roles on the same GPE. Specifically, suffixes like `_coordinator` and `_worker` will be added, where `_coordinator` refers to the worker manager and `_worker` refers to the worker node. @@ -622,11 +626,19 @@ When you write to an S3 path, any existing object will be overwritten. == Query parameter types -Input parameters to a query can be base type (except `EDGE` , `JSONARRAY`, or `JSONOBJECT`). -A parameter can also be a `SET` or `BAG` which uses base type (except `EDGE` , `JSONARRAY`, or `JSONOBJECT`) as the element type. A `FILE` object can also be a parameter. -Within the query, `SET` and `BAG` are converted to xref:accumulators.adoc#_setaccum[`SetAccum`] and xref:accumulators.adoc#_bagaccum[`BagAccum`], respectively. +A query can have one or more input parameters having any of the following types: -[WARNING] +* xref:#_base_types[Base types] (except `EDGE` , `JSONARRAY`, or `JSONOBJECT`). +* xref:#_file_object[FILE object] +* A `SET` or `BAG` of base type elements (except `EDGE` , `JSONARRAY`, or `JSONOBJECT`). +* As of 4.2, `LIST` and `MAP` of base type elements are also supported. The key and value of a `MAP` may be xref:ddl-and-loading:attribute-data-types.adoc#_primitive_types[primitiveType] (numerical, string, or Boolean). + +Within the query, `SET`, `BAG`, `LIST`, and `MAP` parameters are converted to xref:accumulators.adoc#_setaccum[`SetAccum`], +xref:accumulators.adoc#_bagaccum[`BagAccum`], +xref:accumulators.adoc#_listaccum[`ListAccum`], and +xref:accumulators.adoc#_mapaccum_[`MapAccum`], respectively. + +[NOTE] ==== A query parameter is immutable. It cannot be assigned a new value within the query. @@ -646,16 +658,22 @@ parameterType := INT | BOOL | VERTEX ["<" vertexType ">"] | DATETIME - | [ SET | BAG ] "<" baseType ">" + | [ SET | BAG | LIST ] "<" baseType ">" + | MAP "<" primitiveType "," primitiveType ">" | FILE ---- -.Examples of collection type parameters +.Examples of base type and collection type parameter declarations [source,gsql] ---- -(SET p1, BAG ids, FILE f1) +(STRING name, BAG ids, SET> friends, FILE f1) ---- +For how to declare the parameters in a query, see xref:querying:query-operations.adoc#_parameters[CREATE QUERY: parameterList]. + +For how to run a query, see +* xref:querying:query-operations.adoc#_query_parameters[Parameters when running a query in the GSQL CLI]. +* xref:{page-component-version}@tigergraph-server:API:gsql-endpoints.adoc#_format_for_parameters_of_query_being_run[Parameters when running a query as a REST endpoint]. diff --git a/modules/querying/pages/declaration-and-assignment-statements.adoc b/modules/querying/pages/declaration-and-assignment-statements.adoc index d6134205..5731d270 100644 --- a/modules/querying/pages/declaration-and-assignment-statements.adoc +++ b/modules/querying/pages/declaration-and-assignment-statements.adoc @@ -8,27 +8,28 @@ This section discusses the different types of declaration and assignment stateme [source,ebnf] ---- ## Declarations ## -accumDeclStmt := - accumType localAccumName ["=" constant] - ["," localASccumName ["=" constant]]* - | accumType globaAccumName ["=" constant] - ["," GlobalAccumName ["=" constant]]* -localAccumName := "@"accumName; -globalAccumName := "@@"accumName; - -baseDeclStmt := baseType name ["=" constant] ["," name ["=" constant]]* -fileDeclStmt := FILE fileVar "(" filePath ")" +accumDeclStmt := accumType localAccumName ["=" constant] + ["," localAccumName ["=" constant]]* + | accumType globalAccumName ["=" constant] + ["," globalAccumName ["=" constant]]* + +localAccumName := "@" accumName; +globalAccumName := "@@" accumName; + +baseDeclStmt := baseType name ["=" constant] ["," name ["=" constant]]* + +fileDeclStmt := FILE fileVar "(" filePath ["," filePermissionCode] ")" fileVar := name +filePath := stringLiteral +filePermissionCode := stringLiteral // octal encoded permission as a string literal localVarDeclStmt := baseType varName "=" expr vSetVarDeclStmt := vertexSetName ["(" vertexType ")"] "=" (seedSet | simpleSet | selectBlock) - simpleSet := vertexSetName | "(" simpleSet ")" | simpleSet (UNION | INTERSECT | MINUS) simpleSet - -seedSet := "{" [seed ["," seed ]*] "}" +seedSet := "{" [seed ["," seed]*] "}" seed := '_' | ANY | vertexSetName @@ -37,10 +38,8 @@ seed := '_' | paramName | "SelectVertex" selectVertParams | vertexVarName - selectVertParams := "(" filePath "," columnId "," (columnId | name) "," - stringLiteral "," (TRUE | FALSE) ")" ["." FILTER "(" condition ")"] - + stringLiteral "," (TRUE | FALSE) ")" ["." FILTER "(" condition ")"] columnId := "$" (integer | stringLiteral) ## Assignment Statements ## @@ -49,21 +48,19 @@ assignStmt := name "=" expr attrAccumStmt := name "." attrName "+=" expr -lAccumAssignStmt := vertexAlias "." localAccumName ("+="| "=") expr +lAccumAssignStmt := vertexAlias "." localAccumName ("+=" | "=") expr -gAccumAssignStmt := globalAccumName ("+=" | "=") expr +gAccumAssignStmt := globalAccumName ("+=" | "=") expr loadAccumStmt := globalAccumName "=" "{" LOADACCUM loadAccumParams - ["," LOADACCUM loadAccumParams]* "}" - + ["," LOADACCUM loadAccumParams]* "}" loadAccumParams := "(" filePath "," columnId ["," columnId]* "," - stringLiteral "," (TRUE | FALSE) ")" ["." FILTER "(" condition ")"] + stringLiteral "," (TRUE | FALSE) ")" ["." FILTER "(" condition ")"] ## Function Call Statement ## funcCallStmt := name ["<" type ["," type]* ">"] "(" [argList] ")" - | globaAccumName ("." funcName "(" [argList] ")")+ + | globalAccumName ("." funcName "(" [argList] ")")+ | "reset_collection_accum" "(" accumName ")" - argList := expr ["," expr]* ---- @@ -404,14 +401,15 @@ A `FILE` object is a sequential text storage object, associated with a text file .EBNF for FILE object declaration [source,ebnf] ---- -fileDeclStmt := FILE fileVar "(" filePath ")" +fileDeclStmt := FILE fileVar "(" filePath ["," filePermissionCode] ")" fileVar := name +filePath := stringLiteral +filePermissionCode := stringLiteral ---- -When a `FILE` object is declared, associated with a particular text file, any existing content in the text file will be erased. -During the execution of the query, content written to or printed to the `FILE` object will be appended to the `FILE` object. -When the query where the `FILE` object is declared finishes running, the content of the `FILE` object is saved to the text file. +Declaring a `FILE` object with a file path erases any existing content in the text file. An optional Linux octal-encoded file permission code (e.g., "764") can be specified to set access permissions. During query execution, content written to the `FILE` object is appended to it. When the query finishes, the content is saved to the text file. +See xref:querying:output-statements-and-file-objects.adoc#_file_println_statement[Output Statements and FILE Objects] for examples of writing to a `FILE` object. ==== Example @@ -421,8 +419,6 @@ When the query where the `FILE` object is declared finishes running, the content include::appendix:example$work_net/declaration_file_object_query.gsql[] ---- - - == Assignment and Accumulate Statements Assignment statements are used to set or update the value of a variable after it has been declared. diff --git a/modules/querying/pages/func/aggregation-functions.adoc b/modules/querying/pages/func/aggregation-functions.adoc index eeb84ea5..61e61158 100644 --- a/modules/querying/pages/func/aggregation-functions.adoc +++ b/modules/querying/pages/func/aggregation-functions.adoc @@ -4,7 +4,14 @@ This page lists the aggregation functions available in the GSQL query language. [NOTE] ==== -The ``DISTINCT`` keyword can be used to include repeated values only once when aggregating. +If the ``DISTINCT`` option is used, then duplicate values are excluded. +By default, duplicate values are included. + +Example: + +`sum([2,2,2])` returns 6. + +`sum(DISTINCT [2,2,2])` returns 2. ==== == avg() @@ -18,6 +25,7 @@ The ``DISTINCT`` keyword can be used to include repeated values only once when a === Description Returns the average of all elements in a set or bag. The function can only take set/bag expressions whose members are numeric types. +Returns 0 if the input set is empty. [discrete] === Return type @@ -55,6 +63,7 @@ avg([3, 2, 1]) -> 2 === Description Returns the size of the set or bag. +Returns 0 if the input set is empty. [discrete] === Return type @@ -93,6 +102,14 @@ count([1, 1, 2, 2) => 4 Returns the member with the maximum value in a set or bag. The function can only take set/bag expressions whose members are numeric types. +[NOTE] +==== +If the input set is empty: + +* If the function is used to aggregate the vertex or edge attributes selected by a SELECT or MERGE clause, then the return value is the minimum possible value for that data type (similar to MaxAccum behavior). +* Otherwise, the return value is 0. +==== + [discrete] === Return type @@ -128,6 +145,16 @@ max([1, 1, 3, 3]) => 3 === Description Returns the member with the minimum value in a set or bag. The function can only take set/bag expressions whose members are numeric types. +Returns 0 if the input set is empty. + +[NOTE] +==== +If the input set is empty: + +* If the function is used to aggregate the vertex or edge attributes selected by a SELECT or MERGE clause, then the return value is the maximum possible value for that data type (similar to MinAccum behavior). +* Otherwise, the return value is 0. +==== + [discrete] === Return type @@ -164,6 +191,7 @@ min([1, 1, 3, 3]) => 1 === Description Returns the standard deviation of all members in a set or bag, assuming the input is a sample. +Returns 0 if the input set is empty. This function uses `N - 1` as the denominator, and should be used when taking a sample of the population for an unbiased estimate. When the standard variation of the entire population is being calculated, `stdevp` should be used. @@ -205,6 +233,7 @@ stdev([1, 2, 3, 4, 5]) => 1.5811388300842 === Description Returns the standard deviation of all members in a set or bag, assuming the input is the population. +Returns 0 if the input set is empty. This function uses `N` as the denominator, and should be used when calculating the standard deviation for an entire population. When the standard variation of only a sample of the population is being calculated, `stDev` should be used. @@ -246,6 +275,7 @@ stdevp([1, 2, 3, 4, 5]) => 1.4142135623731 === Description Returns the sum of all members in a set or bag. The function can only take set/bag expressions whose members are numeric types. +Returns 0 if the input set is empty. [discrete] === Return type diff --git a/modules/querying/pages/func/context-functions.adoc b/modules/querying/pages/func/context-functions.adoc index 0154c5fb..bf8215dd 100644 --- a/modules/querying/pages/func/context-functions.adoc +++ b/modules/querying/pages/func/context-functions.adoc @@ -3,15 +3,15 @@ Context functions are a set of built-in functions that provide insights into the user's information during their current session. They offer valuable insights into user roles, making it easier to manage access and privileges within TigerGraph. -They work in: `INSTALLED` queries, `INTERPRET` queries, and xref:tigergraph-server:user-access:rbac-row-policy/rbac-row-policy.adoc#_gsql_functions[GSQL Functions]. +They work in: `INSTALLED` queries, `INTERPRET` queries, and xref:{page-component-version}@tigergraph-server:user-access:rbac-row-policy/rbac-row-policy.adoc#_gsql_functions[GSQL Functions]. == Enable Context Functions Before users can use Context Functions, you must enable REST++ authentication. If it's not enabled, users will see an error message. -To learn more about REST++ authentication see xref:tigergraph-server:API:authentication.adoc[REST API Authentication]. +To learn more about REST++ authentication see xref:{page-component-version}@tigergraph-server:API:authentication.adoc[REST API Authentication]. -In order to use the context functions explicitly, ensure that the user holds the `READ_ROLE` privilege on the current graph, unless a xref:tigergraph-server:user-access:rbac-row-policy/setup-row-policy.adoc#_row_policy[Row Policy] already includes the xref:tigergraph-server:user-access:rbac-row-policy/rbac-row-policy.adoc#_context_functions[Context Functions]. +In order to use the context functions explicitly, ensure that the user holds the `READ_ROLE` privilege on the current graph, unless a xref:{page-component-version}@tigergraph-server:user-access:rbac-row-policy/setup-row-policy.adoc#_row_policy[Row Policy] already includes the xref:{page-component-version}@tigergraph-server:user-access:rbac-row-policy/rbac-row-policy.adoc#_context_functions[Context Functions]. == current_roles() diff --git a/modules/querying/pages/func/datetime-functions.adoc b/modules/querying/pages/func/datetime-functions.adoc index 2575b3cb..1935b5e9 100644 --- a/modules/querying/pages/func/datetime-functions.adoc +++ b/modules/querying/pages/func/datetime-functions.adoc @@ -136,7 +136,7 @@ The default value for this parameter is `+"%Y-%m-%d %H:%M:%S"+` [source,text] ---- -datetime_format(to_datetime("2020-01-02 05:30:12"), "hi, it's %Y-%m-%d") +(datetime_format("2020-01-02 05:30:12"), "hi, it's %Y-%m-%d") -> "hi, it's 2020-01-02" ---- diff --git a/modules/querying/pages/func/list-functions.adoc b/modules/querying/pages/func/list-functions.adoc index 3d8aaab6..24afc468 100644 --- a/modules/querying/pages/func/list-functions.adoc +++ b/modules/querying/pages/func/list-functions.adoc @@ -4,21 +4,21 @@ This page lists the list (ListAccum) functions that are available in the GSQL query language. -=== `head()` +== `head()` -==== Syntax +=== Syntax `head(list)` -==== Description +=== Description `head()` returns the first element in a list. It is semantically the same as `list.get(0)` -==== Return type +=== Return type `ELEMENT` -==== Parameters +=== Parameters |=== | Parameter | Description | Data type @@ -27,27 +27,27 @@ This page lists the list (ListAccum) functions that are available in the GSQL qu | `ListAccum` |=== -==== Example +=== Example [source,text] ---- head(["a", "b", "c"]) -> "a" ---- -=== `last()` +== `last()` -==== Syntax +=== Syntax `last(list)` -==== Description +=== Description `last()` returns the last element in a list. It is semantically the same as `list.get(list.size() - 1)` -==== Return type +=== Return type `ELEMENT` -==== Parameters +=== Parameters |=== | Parameter | Description | Data type @@ -56,27 +56,27 @@ head(["a", "b", "c"]) -> "a" | `ListAccum` |=== -==== Example +=== Example [source,text] ---- last(["a", "b", "c"]) -> "c" ---- -=== `range()` +== `range()` -==== Syntax +=== Syntax `range(start, end [, step])` -==== Description +=== Description `range()` returns a `ListAccum` of integer values within a range bounded by a start value `start` and end value `end`, and an optional step size `step`. The range is inclusive, so the arithmetic progression will always contain `start`, and it may contain `end`value, depending on the step size. -==== Return type +=== Return type `ListAccum` -==== Parameters +=== Parameters |=== | Parameter | Description | Data type @@ -95,7 +95,7 @@ The difference between any two consecutive values in the range | `UINT`, `INT` |=== -==== Example +=== Example [source,text] ---- range(0, 5) -> [0, 1, 2, 3, 4, 5] @@ -109,21 +109,21 @@ range(2, 18, 3) -> [2, 5, 8, 11, 14, 17] * For large ranges, the range() function can consume significant memory, as it generates the entire list before iteration. ==== -=== `size()` +== `size()` -==== Syntax +=== Syntax `size(list)` -==== Description +=== Description `size()` returns the number of elements in a `ListAccum` -==== Return type +=== Return type `UINT` -==== Parameters +=== Parameters |=== | Parameter | Description | Data type @@ -132,27 +132,27 @@ range(2, 18, 3) -> [2, 5, 8, 11, 14, 17] | `ListAccum` |=== -==== Example +=== Example [source,text] ---- size(["a", "b", "c"]) -> 3 ---- -=== `split()` +== `split()` -==== Syntax +=== Syntax `split(original, splitDelimiter)` -==== Description +=== Description `split()` returns a list of strings resulting from the splitting of the original string on matches of the given delimiter. -==== Return type +=== Return type `ListAccum` -==== Parameters +=== Parameters |=== | Parameter | Description | Data type @@ -165,28 +165,28 @@ size(["a", "b", "c"]) -> 3 | `STRING` |=== -==== Example +=== Example [source,text] ---- split("one,two", ",") -> ["one", "two"] split("aaabcaabca", "abc") -> ["aa", "a", "a"] ---- -=== `tail()` +== `tail()` -==== Syntax +=== Syntax `tail(list)` -==== Description +=== Description `tail()` returns the copy of the list that includes all but the first element in the parameter list. -==== Return type +=== Return type `ListAccum` -==== Parameters +=== Parameters |=== | Parameter | Description | Data type @@ -195,7 +195,7 @@ split("aaabcaabca", "abc") -> ["aa", "a", "a"] | `ListAccum` |=== -==== Example +=== Example [source,text] ---- tail(["a", "b", "c"]) -> ["b", "c"] diff --git a/modules/querying/pages/func/query-user-defined-functions.adoc b/modules/querying/pages/func/query-user-defined-functions.adoc index cfc81f82..ea940dd5 100644 --- a/modules/querying/pages/func/query-user-defined-functions.adoc +++ b/modules/querying/pages/func/query-user-defined-functions.adoc @@ -1,6 +1,5 @@ = Query User-Defined Functions :pp: {plus}{plus} -:sectnums: :description: Instructions to define UDFs in the GSQL Query language. In GSQL, users can supplement the language by defining their own query user-defined functions (query UDFs) in C{pp}. @@ -13,8 +12,8 @@ Once defined, the new functions are added into GSQL automatically the next time UDFs are written in C{pp} in two files, `ExprFunctions.hpp` and `ExprUtil.hpp`: -* ExprFunctions is used for functions that are called directly in GSQL queries. -* ExprUtil contains structs or helper functions that are used by the functions in ExprFunctions. +* `ExprFunctions` is used for functions that are called directly in GSQL queries. +* `ExprUtil` contains structs or helper functions that are used by the functions in `ExprFunctions`. The functions defined in `ExprUtil.hpp` cannot be used in a GSQL query. == UDF security @@ -35,7 +34,7 @@ All UDF files are scanned by the system to ensure that they comply with the UDF * There is a file header allowlist that restricts the possible file headers to a customizable list. * Additional C{plus}{plus} features are disabled for security reasons. -For more details, see xref:tigergraph-server:security:index.adoc#_udf_file_scanning[Security - UDF file scanning]. +For more details, see xref:{page-component-version}@tigergraph-server:security:index.adoc#_udf_file_scanning[Security - UDF file scanning]. [#_define_a_query_udf_in_cpp] == Define a query UDF in C{pp} @@ -74,9 +73,9 @@ inline bool greater_than_three (double x) { | All other C{pp} data types | *No* | *No* | Yes |=== -You can write your functions in the `ExprFunctions` file provided as a sample in TigerGraph Server installations, or create your own `.hpp` files from scratch. +You can place your functions in the `ExprFunctions.hpp` file provided as a sample in TigerGraph Server installations, or create your own file from scratch. -If your function requires a user-defined struct or helper function, that struct or helper function must be defined in a separate `ExprUtil` file. +If your function requires a user-defined struct or helper function, that struct or helper function must be defined in a separate `ExprUtil.hpp` file. [NOTE] C{pp} supports changing the value of a `for` loop variable within a loop. @@ -101,13 +100,25 @@ inline string reverse(string str){ There are two ways to modify the UDF files to add user-defined functions to GSQL. Both are secured by `gadmin` and require administrator-level access: -* Store UDF files in a GitHub repository, and configure GSQL to read from the repository. +* xref:_use_github_to_store_udfs[Store UDF files in a GitHub repository], and configure GSQL to read from the repository. ** This is the recommended approach. It also takes the highest precedence. If GSQL is configured to read from GitHub for UDFs and the configurations are valid, UDFs in other sources are ignored. -* Use the GSQL `PUT` command to upload UDFs. +* xref:#_upload_udfs_with_gsql_put_command[Use the GSQL `PUT` command to upload UDFs]. ** For security reasons, this method is disabled by default, and can only be enabled by the TigerGraph Linux user with access to `gadmin`. +[#udf_update_warning] +[IMPORTANT] +.Query reactivation required if UDFs are modified +==== +If the UDF files change, either through GitHub or `PUT`, then any existing installed queries which use any UDF, whether modified or not, will be disabled as a precaution. +To re-enable them: + +. Check each disabled query to see if the UDF change causes a need to revise the query. Make necessary modifications. +. Run `CREATE OR REPLACE QUERY` for each disabled query. +. Run `INSTALL QUERY`, singly or for a batch of queries. +==== + === Use GitHub to store UDFs You can configure GSQL to read from a GitHub repository for ExprFunctions and ExprUtil. @@ -116,8 +127,6 @@ This is TigerGraph's recommended approach to managing UDFs. If GitHub access is configured, GSQL retrieves user source code files from GitHub before other sources, so long as the files exist on GitHub. If GitHub is connected but files are missing, TigerGraph looks for a UDF file added locally with the `PUT` command. -New additions to the files in the GitHub repository are instantly available in GSQL. - You can retrieve ExprFunctions.hpp and ExprUtil.hpp from `AppRoot/dev/gdk/gsql/src/QueryUdf/ExprFunctions.hpp` and copy them to a Git repository of your choice. The file names must be `ExprFunctions.hpp` and `ExprUtil.hpp`. @@ -133,9 +142,16 @@ The `gadmin` configuration parameters for setting up the connection to GitHub ar | `GSQL.GithubBranch` | The branch to access | `main` | `GSQL.GithubPath` | Path to the directory in the repository that has ExprFunctions.hpp and ExprUtil.hpp | `src/` | `GSQL.GithubUrl` | Optional parameter used for GitHub Enterprise | `https://api.github.com` +| `GSQL.GithubEnabled` | To Enable the retrieval of UDFs (such as ExprFunctions.hpp, ExprUtils.hpp, etc.) from GitHub (default `false`). | `false` |=== + +[NOTE] +==== +When upgrading the database from a version where the parameter `GSQL.GithubEnabled` did not exist (pre 4.1.3) to one where it does, the upgrade process will set `GSQL.GithubEnabled` to `true`. +==== + -Use the xref:tigergraph-server:system-management:management-commands.adoc#_gadmin_config_set[`gadmin config set`] command to configure the aforementioned parameters to connect GSQL to the GitHub repository hosting your files. +Use the xref:{page-component-version}@tigergraph-server:system-management:management-commands.adoc#_gadmin_config_set[`gadmin config set`] command to configure the aforementioned parameters to connect GSQL to the GitHub repository hosting your files. The following is an example configuration. Remember to run `gadmin config apply` after changing the parameters. @@ -152,9 +168,19 @@ gadmin config apply After the parameters are successfully configured, you can access your UDFs in new queries right away. +==== Update UDFs sourced from GitHub + +For versions prior to 4.1, each time GSQL is run, it checks to see if the UDF files on GitHub have changed. +If they had, it downloads the new UDF files. + +Beginning in 4.1, GSQL only checks GitHub if more than one hour has elapsed since the last check. +To force GSQL to install new UDF files from GitHub, run `gadmin restart all` to restart GSQL. + +See the note about xref:#udf_update_warning[some queries disabled after UDFs are updated]. + === Upload UDFs with GSQL `PUT` command TigerGraph offers the ability to upload UDFs directly from GSQL using the `PUT` command. -This command is securely managed by xref:tigergraph-server:system-management:management-commands.adoc[ the management tool `gadmin`] and is disabled by default, requiring a Tigergraph Linux user with gadmin access to enable it. +This command is securely managed by xref:{page-component-version}@tigergraph-server:system-management:management-commands.adoc[ the management tool `gadmin`] and is disabled by default, requiring a Tigergraph Linux user with gadmin access to enable it. After making modifications to your UDF files, it is recommended that you disable the ability to upload UDF files using `PUT` until you need to modify the files again ==== Enable uploading UDFs through GSQL @@ -204,6 +230,7 @@ PUT ExprUtil successfully. ---- The `PUT` command automatically uploads the files in all nodes in a cluster and updates all existing files. +See the note about xref:#udf_update_warning[some queries disabled after UDFs are updated]. Once the files are stored, you can call the UDFs in a query the next time GSQL is executed. This includes the next time you start the GSQL shell or execute GSQL scripts from a bash shell. diff --git a/modules/querying/pages/func/vertex-methods.adoc b/modules/querying/pages/func/vertex-methods.adoc index d34eb004..38364e04 100644 --- a/modules/querying/pages/func/vertex-methods.adoc +++ b/modules/querying/pages/func/vertex-methods.adoc @@ -317,10 +317,10 @@ In this case, outdegree() can be used in a xref:querying:query-operations.adoc#_ |=== [CAUTION] - ==== -*Note on outdegree()*: This function reads a metadata value stored with each vertex, to avoid traversing the graph and thus have a fast response. The snapshot transaction semantics means that outdegree() may sometimes read an old value if there are concurrent write transactions. To guarantee an accurate count, traverse the neighboring edges and count them with a SumAccum, or use a function like neighbors() and then use size() on the set. - +*Note on outdegree()*: The outdegree() function reads a stored metadata value for faster performance instead of traversing the graph. +Because of snapshot transaction semantics, `outdegree()` might show an outdated value if there are *write transactions running or have just finished*. This delay happens because the background rebuild task may not have processed the updates yet. +To get an exact count, traverse the edges manually using a `SumAccum`, or use the `neighbors()` function and apply `size()` on the result. ==== ==== Examples diff --git a/modules/querying/pages/operators-and-expressions.adoc b/modules/querying/pages/operators-and-expressions.adoc index 93fe5521..15097cb9 100644 --- a/modules/querying/pages/operators-and-expressions.adoc +++ b/modules/querying/pages/operators-and-expressions.adoc @@ -1,69 +1,10 @@ = Operators and Expressions -An _expression_ is a combination of fixed values, variables, operators, function calls, and groupings that specify a computation, resulting in a data value. This section of the specification describes the literals (fixed values), operators, and functions available in the GSQL query language. It covers the subset of the EBNF definitions shown below. - -However, more so than in other sections of the specification, syntax alone is not an adequate description. The semantics (functionality) of the particular operators and functions are an essential complement to the syntax. - -.EBNF for Operations, Functions, and Expressions -[source,ebnf] ----- -constant := numeric | stringLiteral | TRUE | FALSE | GSQL_UINT_MAX - | GSQL_INT_MAX | GSQL_INT_MIN | TO_DATETIME "(" stringLiteral ")" - -mathOperator := "*" | "/" | "%" | "+" | "-" | "<<" | ">>" | "&" | "|" - -condition := expr - | expr comparisonOperator expr - | expr [ NOT ] IN setBagExpr - | expr IS [ NOT ] NULL - | expr BETWEEN expr AND expr - | "(" condition ")" - | NOT condition - | condition (AND | OR) condition - | (TRUE | FALSE) - | expr [NOT] LIKE expr [ESCAPE escape_char] - -comparisonOperator := "<" | "<=" | ">" | ">=" | "==" | "!=" - -aggregator := COUNT | MAX | MIN | AVG | SUM - -expr := name - | globalAccumName - | name ".type" - | name "." name - | name "." localAccumName ["\'"] - | name "." name "." name "(" [argList] ")" - | name "." name "(" [argList] ")" [ "." FILTER "(" condition ")" ] - | name ["<" type ["," type]* ">"] "(" argList] ")" - | name "." localAccumName ("." name "(" [argList] ")")+ ["." name] - | globalAccumName ("."name "(" [argList] ")")+ ["."name] - | COALESCE "(" [argList] ")" - | aggregator "(" [DISTINCT] setBagExpr ")" - | ISEMPTY "(" setBagExpr ")" - | expr mathOperator expr - | "-" expr - | "(" expr ")" - | "(" argList "->" argList ")" // key value pair for MapAccum - | "[" argList "]" // a list - | constant - | setBagExpr - | name "(" argList ")" // function call or a tuple object - -setBagExpr := name - | globalAccumName - | name "." name - | name "." localAccumName - | name "." localAccumName ("." name "(" [argList] ")")+ - | name "." name "(" [argList] ")" [ "." FILTER "(" condition ")" ] - | globalAccumName ("." name "(" [argList] ")")+ - | setBagExpr (UNION | INTERSECT | MINUS) setBagExpr - | "(" argList ")" - | "(" setBagExpr ")" - - -argList := expr ["," expr]* ----- +An _expression_ is a combination of fixed values, variables, operators, function calls, and groupings that specify a computation, resulting in a data value. This section of the specification describes the literals (fixed values), operators, and functions available in the GSQL query language. +This section focuses on xref:_constants[constants], xref:_vertex_edge_and_accumulator_attributes[vertex and edge attributes], xref:_operators[operators], and xref:_subqueries[subqueries]. +Because xref:func/index.adoc[] are so numerous, they are covered in their own section. +Beginning in versions 4.1.2 and 4.2.0, xref:_case_expressions[CASE expressions] are also available. == Constants @@ -249,7 +190,7 @@ A condition is an expression that evaluates to a boolean value of either true or [source,ebnf] ---- -comparisonOperator := "<" | "<=" | ">" | ">=" | "==" | "!=" +comparisonOperator := "<" | "<=" | ">" | ">=" | "==" | "!=" | "=" | "<>" condition := expr | expr comparisonOperator expr @@ -263,6 +204,8 @@ condition := expr | expr [NOT] LIKE expr [ESCAPE escape_char] ---- +In GSQL V3, starting with version 4.1.3, we support the use of the equality operator `=` and the inequality operator `<>` in addition to the existing `==` and `!=` operators. + Strings are compared based on standard lexicographical ordering: + (space) < (digit) < (uppercase_letter) < (lowercase_letter). @@ -281,7 +224,7 @@ include::appendix:example$minimal_net/operators_expressions_between_and.gsql[] === IS NULL, IS NOT NULL -`IS NULL` and `IS NOT NULL` can be used for checking whether an optional parameter is given any value. +`IS NULL` and `IS NOT NULL` can be used for checking whether an optional expression is given any value. ==== Example @@ -325,9 +268,29 @@ Every attribute value stored in GSQL is a valid value, so IS NULL and IS NOT NUL expr [NOT] LIKE expr [ESCAPE escape_char] ---- -The `LIKE` operator is used for string pattern matching and can only be used in `WHERE` clauses. The expression `string1 LIKE string_pattern` evaluates to boolean true if `string1` matches the pattern in `string_pattern`; otherwise, it is false. +The `LIKE` operator is used for string pattern matching in GSQL and can be used just like any other condition in the query. The expression `string1 LIKE string_pattern` evaluates to `true` if `string1` matches the pattern specified in `string_pattern`; otherwise, it evaluates to `false`. -Both operands must be strings. Additionally, while `string1` can be a function call (e.g. `lower(string_variable)`, `string_pattern` must be a string literal or a parameter. `string_pattern` cannot be the result of concatenating other strings, nor can it be a function call. +In 4.2, the operand `string_pattern` can now be any expression. This includes string concatenation, function calls, or other valid expressions, which can be used directly in the `LIKE` operator. + +For example, the following is now valid in GSQL: + +[source,gsql] +---- +CREATE OR REPLACE QUERY like_with_func(string str2="%lliH nomaD htiw%"){ + STRING str1 = "%Benjamin% Franklin%"; + + Message = SELECT t FROM Person:s -(LIKES>:e1)- :mid -(REPLY_OF>:e2) - :t + WHERE t.content LIKE lpad(str1, 10) + OR t.content LIKE replace("Et Salvador", "t", "l") + OR t.content LIKE reverse(str2) + ORDER BY t.id DESC + LIMIT 20; + + PRINT Message; +} +---- + +The restriction that `string_pattern` must be a string literal or parameter has been lifted in 4.2. Now, function calls like `lpad()` or `replace()` and expressions like `reverse(str2)` can be used to define the pattern. A `string_pattern` can contain characters as well as the following wildcard and other special symbols, in order to express a pattern (`` indicates a placeholder): @@ -379,7 +342,7 @@ Then: * The actual value of `Vertex.attribute` in the graph is `"\\abc"`. The size of the string is 4, because the first backslash is used to escape the second backslash and doesn't count towards the size of the string. -* `Vertex.attribute == "\\abc"` returns true, because a backslash is required to escape the other backslash. +* `Vertex.attribute == "\\abc"` returns true, because a backslash is required to escape the other backslash. * `Vertex.attribute LIKE "\\\\abc"` returns true, because it takes two backslashes in a string pattern to match one backslash in a string. ==== @@ -396,13 +359,19 @@ The first `"%"` has its usual pattern-matching meaning "zero or more characters" [tabs] ==== -Query Without Parameters:: +Query with Constant Strings:: + -- .Example query using LIKE operator [source,gsql] ---- -include::appendix:example$social_net/operators_expressions_query_without_parameters.gsql[] +CREATE QUERY print_a_posts() FOR GRAPH Social_Net { + posts = {Post.*}; + a_posts = SELECT v FROM posts:v + // Returns all posts with the character "a" in the subject + WHERE v.subject LIKE "%a%"; + PRINT a_posts; +} ---- -- Query With Parameters:: @@ -411,8 +380,36 @@ Query With Parameters:: .Example parameterized query [source,gsql] ---- -include::appendix:example$social_net/operators_expressions_query_with_parameters.gsql[] +CREATE QUERY print_posts(STRING search_string) FOR GRAPH Social_Net { + STRING search_param; + search_param = "%" + search_string + "%"; + posts = {Post.*}; + a_posts = SELECT v FROM posts:v + // Returns all posts with the search_string in the subject + WHERE v.subject LIKE search_param; + PRINT a_posts; +} +---- +-- +Query with Complex Expressions:: ++ +-- +.Example query using the LIKE operator with complex expressions +[source,gsql] +---- +CREATE OR REPLACE QUERY like_with_func(string str2="%lliH nomaD htiw%"){ + STRING str1 = "%Benjamin% Franklin%"; + + Message = SELECT t FROM Person:s -(LIKES>:e1)- :mid -(REPLY_OF>:e2) - :t + WHERE t.content LIKE lpad(str1, 10) + OR t.content LIKE replace("Et Salvador", "t", "l") + OR t.content LIKE reverse(str2) + ORDER BY t.id DESC + LIMIT 20; + + PRINT Message; +} ---- -- Results:: @@ -598,6 +595,75 @@ include::appendix:example$social_net/operators_expressions_set_membership_result ==== +[#_case_expressions] +== CASE Expressions + +Available in version 4.1.2+ + +A CASE expression provides a set of possible resulting values, each one associated with a different conditional test. +The conditions are presented in a sequence of `WHEN... THEN` clauses, so that the `CASE` expression as a whole is assigned the value associated with the first condition that is true. +Any conditions that come after the first true condition are skipped. +If none of the conditions are true, then the `ELSE` clause sets the value. + +Two forms of the CASE expression are available. The first is the general form: + + +.General CASE syntax +[source,ebnf] +---- +caseExpr := + CASE + WHEN condition THEN value + [WHEN condition THEN value]* + ELSE value + END +---- + +[discrete] +=== Example +[source,ebnf] +---- +numDays = + CASE + WHEN (year % 400) == 0 THEN 366 + WHEN (year % 100) == 0 THEN 365 + WHEN (year % 4) == 0 THEN 366 + ELSE 365 +---- + +A second version of the `CASE` expression presents a single test expression at the outset. +Each `WHEN... THEN` clause presents its own expression. +The `CASE` expression selects the clause whose `WHEN` expression value is equal to the test expression's value. +Again, an `ELSE` clause is available. + +.CASE syntax with test expression +[source,ebnf] +---- +caseExprVar := + CASE testExpression + WHEN expression THEN value + [WHEN expression THEN value]* + ELSE value + END + +testExpression := expression +---- + +[discrete] +=== Example +[source,ebnf] +---- +points = + CASE event + WHEN "touchdown" THEN 6 + WHEN "kicked extra point" THEN 1 + WHEN "two point conversion" THEN 2 + WHEN "safety" THEN 2 + WHEN "field goal" THEN 3 + ELSE 0 + END +---- + [#_subqueries] == Subqueries @@ -805,4 +871,4 @@ GSQL > RUN QUERY expression_stmnt_ex() include::appendix:example$work_net/operators_expressions_expression_statement_results.json[] ---- -- -==== \ No newline at end of file +==== diff --git a/modules/querying/pages/output-statements-and-file-objects.adoc b/modules/querying/pages/output-statements-and-file-objects.adoc index 6217b5ae..6937c623 100644 --- a/modules/querying/pages/output-statements-and-file-objects.adoc +++ b/modules/querying/pages/output-statements-and-file-objects.adoc @@ -12,9 +12,8 @@ A `PRINT` statement can appear wherever query-body statements are permitted. A `PRINT` statement does not trigger immediate output. The full set of data from all PRINT statements is delivered at one time, when the query concludes. -A query can print a maximum of 2GB of data. - -If the output is to a `FILE` object, then the size limit does not apply. +If the query response is large, it is recommended to use `PRINT … TO_CSV`. +TigerGraph currently does not support pagination; returning a large query response in a single response via the GSQL terminal or RESTPP may lead to excessive memory usage and make the response difficult to parse efficiently. ==== .EBNF @@ -453,8 +452,7 @@ Each execution of the `PRINT` statement appends one line to the `FILE`. If the ` ==== Limitations of `PRINT` > File -* Printing a full Vertex set variable is not supported. -* If a vertex is printed, only its ID value is printed. +* In 4.2.1, printing a full vertex set is supported with `PRINT vt`; and `PRINT vt TO_CSV f`;. Only vertex IDs are printed. * If printing a vertex set's vertex-attached accumulator or a vertex set's variable, the result is a list of values, one for each vertex, separated by newlines. * The syntax for printing a vertex set expression is different when printing to a file than when printing to standard output. Compare: ** `PRINT A[A.gender];` # with brackets @@ -488,7 +486,6 @@ printlnStmt := fileVar".println" "(" expr ("," expr)* ")" ---- - `println` is a method of a FILE object variable. The `println` statement can be used either at the query-body or DML-sub-statement level, e.g., within the `ACCUM` clause of a `SELECT` block. Each time `println` is called, it adds one new line of values to the `FILE` object, and then to the corresponding file. The `println` function can print any expression that can be printed by a `PRINT` statement with the exception of vertex set variables. Vertex expression sets are also not applicable to the `println` function. @@ -501,27 +498,29 @@ The data from query-body level `FILE` print statements (either `TO_CSV` or `prin ==== [discrete] -==== Example +=== Example + +As of 4.2.1, users can declare a FILE object with a linux octal-encoded file permission code to specify file permissions. +See xref:querying:declaration-and-assignment-statements.adoc#_file_objects[Declaration and Assignment Statements] page for details. .File object query example [source,gsql] ---- include::appendix:example$work_net/output_statements_file_object_query_example.gsql[] -INSTALL QUERY file_ex -RUN QUERY file_ex("/home/tigergraph/files") +INSTALL QUERY get_US_worker_interests +RUN QUERY get_US_worker_interests("/home/tigergraph/fileEx.txt") ---- - All of the `PRINT` statements in this example use the `TO_CSV` option, so there is no JSON output to the console. -.Results from Query fileEx +.Results from Query get_US_worker_interests [source,gsql] ---- -GSQL > RUN QUERY file_ex("/home/tigergraph/file_ex.txt") +GSQL > RUN QUERY get_US_worker_interests("/home/tigergraph/fileEx.txt") { "error": false, "message": "", @@ -534,15 +533,13 @@ GSQL > RUN QUERY file_ex("/home/tigergraph/file_ex.txt") } ---- - - All the output in this case goes to the `FILE` object. In the query definition, the line `"header"` is printed first, followed by the `println` statements in the `ACCUM` clause, and `"footer"` is printed last. The output in the file follows this order because the order of query-body level statements is maintained in the output. -.File contents produced by file_ex example +.File contents produced by get_US_worker_interests example [source,gsql] ---- -[tigergraph@localhost]$ more /home/tigergraph/file_ex.txt +[tigergraph@localhost]$ more /home/tigergraph/fileEx.txt header person7,art sport person10,football sport @@ -553,7 +550,6 @@ footer ---- - However, within the `ACCUM` clause itself, the order of the `println` statements is not guaranteed. == Passing a FILE Object as a Parameter diff --git a/modules/querying/pages/query-modes.adoc b/modules/querying/pages/query-modes.adoc new file mode 100644 index 00000000..865a5675 --- /dev/null +++ b/modules/querying/pages/query-modes.adoc @@ -0,0 +1,251 @@ += Querying Choices +:description: Explains the options that TigerGraph users have for querying - language choice, execution mode, and API choice + +The TigerGraph database provides users with a wide range of choices for how to write and run queries, letting you choose what is the best fit for your needs and preferences. + +This page presents the options in a simple outline, pointing out the advantages and typical use cases for each mode or option. It then directs you to where you can learn in more detail about each option. + +The following sections will summarize the options in four areas: + +* xref:#_query_languages[] +* xref:#_query_structure[] +* xref:#_query_apis[] +* xref:#_query_execution_modes[] + +== Query Languages + +Query Language Options: + +* xref:#_gsql[] | xref:#_opencypher[] | xref:#_gql[] + +=== GSQL + +GSQL is xref:index.adoc[TigerGraph's original native language]. +it offers graph traversal and pattern matching queries using declarative syntax similar to SQL, extends it for procedural programming to enable more complex algorithmic querying, adds _xref:querying:accumulators.adoc[accumulators]_ for efficient analytics, and installs (pre-compiles) queries to optimize the execution performance. + +GSQL is more than just for xref:querying:query-operations.adoc[querying] and xref:ddl-and-loading:defining-a-graph-schema.adoc[schema definition]. +It also includes a xref:ddl-and-loading:index.adoc[data loading language] to define stored procedures (jobs) that map and transform data from tabular sources to a graph. + +=== OpenCypher + +openCypher is a popular open-source declarative query language for property graphs. It is well suited for basic graph traversal queries and pattern matching queries. More about openCypher can be found at http://opencypher.org[openCypher.org]. + +GSQL V3 Syatax xref:openCypher-in-gsql:index.adoc[supports the majority of openCypher features], embedded within its native GSQL framework. +To learn to how to run OpenCypher on TigerGraph, see the link:https://github.com/tigergraph/ecosys/blob/master/tutorials/Cypher.md[OpenCypher in GSQL tutorial]. + +=== GQL + +GQL is a new ISO standard for a property graph query language. +Its initial version was published in 2024, focusing on pattern matching queries. +TigerGraph was and is a contributing member of the ISO GQL committee. + +GQL borrows from and extends both OpenCypher and GSQL, enabling a graceful transition for users. +link:https://github.com/tigergraph/ecosys/blob/master/tutorials/GSQL.md[GSQL's V3 Syntax for path patterns] aligns with GQL's syntax. +GQL can work with both schema-first and schema-optional graph databases. + +TigerGraph currently supports the path pattern matching syntax (the `MATCH` or `FROM` clause) of GQL. + +[TIP] +==== +* Use GSQL for analytical and algorithmic queries. +* Use OpenCypher for graph traversal queries if you are already familar with it. +* Become familiar with V3 syntax to learn GQL. +==== + +== Query Structure + +Query Structure Options: + +* Stored Procedure (Procedural and Saved) +* Anonymous (Procedural and Ad Hoc) +* Non-Procedural (Ad Hoc) + +=== Stored Procedure Queries + +Originally, all GSQL queries were *stored procedures*. +A stored procedure is a named sequence of executable statements that is *saved*, and then executing by calling it by name. +Key characteristics: + +* Looping and conditional flow, to implement algorithms and analytics +* Input parameters +* A header and body. The body is bounded by curly braces. +* Output must be explicitly requested with PRINT statements. + +NOTE: Since this was the only query structure format for some time, we will often simply refer to this choice as a *GSQL query*. + +.Example of a Stored Procedure Query +[console] +---- +CREATE QUERY topMovies(INT year, INT k) { + +topK = SELECT m FROM (m:Movie) WHERE m.year == year + ORDER BY m.boxoffice DESC + LIMIT k; +PRINT topK; +} +---- + +=== Anonymous Queries + +There are times when you will run a only query one or a few times. +You may not want to bother to first save it by name and then call it; you just want to run it. You may be exploring the data as you go, without a full plan in advance. You are building an application that will construct and run custom queries based on the interests of the end user's real time behavior and requests. +Similar to a stored procedura query, except + +* no name +* no parameters +* Still has a header, delimited body, and explicit output. + +.Example of an Anonymous Query +[console] +---- +INTERPRET QUERY () { + +topK = SELECT m FROM (m:Movie) WHERE m.year == 1939 + ORDER BY m.boxoffice DESC + LIMIT 10; +PRINT topK; +} +---- + + +=== Non-Procedural Queries + +Starting with version 4.2, TigerGraph can run non-procedural queries. +This is very much like the composition of SQL queries: + +* No header. +* Output is automatic. +* Queries consisting of a single query statement/block do not need to define the body's start and end. +* Optionally, can use `BEGIN` and `END` to delimit a multi-line query. + +.Example of an Non-Procedural Query +[console] +---- +SELECT m FROM (m:Movie) WHERE m.year == 1939 ORDER BY m.boxoffice DESC LIMIT 10 +---- + +[IMPORTANT] +==== +Stored procedural queries with are installed (see Execution Modes) before running will always run faster and more effiiently, sometimes much faster. +==== + +== Query APIs + +There are four major APIs for running queries and performing other database operations: + +* xref:basics:running-gsql.adoc[GSQL command line interface] (aka GSQL Shell) +* xref:{page-component-version}@tigergraph-server:API:index.adoc[REST endpoints] +* Graphical user interface, in xref:gui:graphstudio:overview.adoc[GraphStudio] or xref:main@savanna:graph-development:gsql-editor/index.adoc[Savanna] +* xref:pytigergraph:core-functions:[pyTigerGraph] Python language driver + +.Query APIs +[cols="1,2,2"] +|=== +| API (link to documentation) | Description | Use Cases + +| xref:basics:running-gsql.adoc[GSQL CLI] +| Classic SQL-like commands +| text-based, interactive user + +| xref:{page-component-version}@tigergraph-server:API:index.adoc[REST endpoints] +| HTTP requests, JSON responses +| General application development + +| xref:gui:graphstudio:overview.adoc[GraphStudio], + xref:main@savanna:graph-development:gsql-editor/index.adoc[Savanna] +| Browser GUI-based interaces for building graphs, developing queries, and running queries +| Cloud users, those who prefer a graphical interface + +| xref:pytigergraph:core-functions:[pyTigerGraph] +| Open-source Python library +| Data science applications based on Python + +|=== + +== Query Execution Modes + +Excecution Mode Options: + +* Install and run a stored procedure query +* Interpret a stored procedure query +* interpret an ad hoc anonymous query +* Interpret a non procedural query +* BONUS: Distributed Mode + +=== Install and run a stored procedure query + +The classic--and still most performant--way to run a GSQL query is to create, install it, and run it. The `INSTALL` step provides a level of optimization that is not available when running in interpreted mode. + +[console] +---- +CREATE QUERY topMovies(INT year, INT k) { + +topK = SELECT m FROM (m:Movie) WHERE m.year == year + ORDER BY m.boxoffice DESC + LIMIT k; +PRINT topK; +} +INSTALL QUERY topMovies +RUN QUERY topMovies(1939, 10) +---- + +=== Interpret a stored procedure query + +When a developer is writing and refining a stored procedure query, they may be rapidly iterating through different versions of the query. +In this case, they may not want to take the time to install the query. +And if they are experimenting with a small database, they may not be concerned with the slower run time. + +In this case, they can simply skip the `INSTALL` step, and use `INTERPRET` instead of `RUN`: + +[console] +---- +CREATE QUERY topMovies(INT year, INT k) { + +topK = SELECT m FROM (m:Movie) WHERE m.year == year + ORDER BY m.boxoffice DESC + LIMIT k; +PRINT topK; +} +INTERPRET QUERY topMovies(1939, 10) +---- + +=== Interpret an ad hoc anonymous query + +If we plan to run a query just once, we can skip the step of saving the query. +The query is not named, and there is no need to have parameters. + +[console] +---- +INTERPRET QUERY () { +topK = SELECT m FROM (m:Movie) WHERE m.year == 1939 +ORDER BY m.boxoffice DESC +LIMIT 10; +PRINT topK; +} +---- + +[NOTE] +==== +When this approach is used by an application that is building the query, users often find the REST API or pyTigerGraph library to be the best fit. +==== + +=== Interpret a non procedural query + +This method, introduced in 4.2, is well-suited both for applications and for interactive users, due to its simplicity. +If you are running the GSQL shell, you simply type in the query with minimal overhead. +There is no `RUN` or `INTERPRET` command; you just submit the query itself. + +[console] +---- +SELECT m FROM (m:Movie) WHERE m.year == 1939 ORDER BY m.boxoffice DESC LIMIT 10 +---- + +For more examples, see the link:https://github.com/tigergraph/ecosys/blob/master/tutorials/GSQL.md#1-block-query-examples[1-Block Query Examples] in the GSQL V3 Tutorial. + +=== Distributed Mode + +We cannot end without mentioning Distributed Mode. +Any procedural query can be run in distributed mode. +It is the more performant mode when the query will traverse a large percentage of your graph, especially if it begins the query not at a single vertex but at a large set of vertices. + +For more information, see the xref:querying:distributed-query-mode.adoc[] page. diff --git a/modules/querying/pages/query-operations.adoc b/modules/querying/pages/query-operations.adoc index 11aa348e..2219b58d 100644 --- a/modules/querying/pages/query-operations.adoc +++ b/modules/querying/pages/query-operations.adoc @@ -1,9 +1,11 @@ -= Queries -:pp: {plus}{plus} += Create and Run Queries :description: Commands in the GSQL query language associated with query operations. +:page-aliases: run-queries.adoc +:pp: {plus}{plus} + A GSQL query is a sequence of data retrieval and computation statements executed as a single operation. -Users can write queries to explore and manipulate data in the graph, perform computations, update the graph, and retrieve results. +Users can write queries to explore and manipulate data in the graph, perform computations, update the graph, and retrieve results. A query functions similarly to a user-defined procedure or function, accepting one or more input parameters and producing output by either returning values or printing results. In addition to querying the graph, you can also manage descriptions for your queries and query parameters. This includes updating, viewing, and removing descriptions, which can help document and clarify the purpose of your queries. @@ -31,8 +33,8 @@ parameterValue := parameterConstant | "[" parameterValue ["," parameterValue]* "]" // BAG or SET | "(" stringLiteral "," stringLiteral ")" // generic VERTEX value parameterConstant := numeric | stringLiteral | TRUE | FALSE -parameterList := parameterType paramName ["=" constant] - ["," parameterType paramName ["=" constant]]* +parameterDeclaration := parameterType paramName ["=" constant] +parameterList := parameterDeclaration ["," parameterDeclaration]* syntaxName := name @@ -78,18 +80,18 @@ queryNamePrefix := name"*" A query can be run in one of three ways: . Define and run an unnamed query immediately: - .. `INTERPRET QUERY`: execute the query's statements +.. `INTERPRET QUERY`: execute the query's statements + Alternately, there is also a built-in REST{pp} endpoint to interpret a query string: + `POST /gsqlserver/interpreted_query` + -See the xref:tigergraph-server:API:index.adoc[RESTPP API User Guide] for details. +See the xref:{page-component-version}@tigergraph-server:API:index.adoc[RESTPP API User Guide] for details. . Define a named query and then run it. - .. `CREATE QUERY`: define the functionality of the query - .. `INTERPRET QUERY`: execute the query with input values +.. `CREATE QUERY`: define the functionality of the query +.. `INTERPRET QUERY`: execute the query with input values . Define a named query, compile it to optimize performance, and then run it. - .. `CREATE QUERY`: define the functionality of the query - .. `INSTALL QUERY`: compile the query - .. `RUN QUERY`: execute the query with input values +.. `CREATE QUERY`: define the functionality of the query +.. `INSTALL QUERY`: compile the query +.. `RUN QUERY`: execute the query with input values There are some limitations to Interpreted Mode. See the section on <> and the appendix section xref:appendix:interpreted-gsql-limitations.adoc[Interpreted GSQL Limitations]. @@ -137,12 +139,13 @@ For details, see xref:distributed-query-mode.adoc[Distributed Query Mode.] `queryName`:: Name of the query. -`parameterList`:: A list of parameters for the query. -The parameter list for a query follows the following form: +`parameterList`:: A comma-separated list of parameters for the query. +Each parameter declaration gives the parameter type, the parameter name, and optionally, the default value of the parameter. + [source,ebnf] ---- -parameterType paramName ["=" constant] ["," parameterType paramName ["=" constant]]* +parameterDeclaration := parameterType paramName ["=" constant] +parameterList := parameterDeclaration ["," parameterDeclaration]* ---- For a list of allowed data types for query parameters, see xref:data-types.adoc#_query_parameter_types[Query parameter types]. @@ -177,7 +180,7 @@ It also supports calling functions, assigning variables, printing, and modifying The query body may include calls to other queries. That is, the other queries are treated as subquery functions. See the subsection on "xref:querying:operators-and-expressions.adoc#_subqueries[subqueries]". + -Additionally, GSQL supports openCypher syntax in the query body. See pages xref:openCypher-in-gsql:openCypher-in-gsql.adoc[], xref:openCypher-in-gsql:openCypher-in-gsql-web-shell.adoc[], and xref:openCypher-in-gsql:openCypher-gsql-from-clause-extension.adoc[] to learn more about openCypher and for examples. +Additionally, GSQL supports openCypher syntax in the query body. See pages xref:openCypher-in-gsql:index.adoc[], xref:openCypher-in-gsql:openCypher-in-gsql-web-shell.adoc[], and xref:openCypher-in-gsql:openCypher-gsql-from-clause-extension.adoc[] to learn more about openCypher and for examples. === Examples @@ -238,7 +241,7 @@ String or string set parameters can be used for edge and target types instead. The xref:querying:func/vertex-methods.adoc[`getAttr` and `setAttr` functions], which take attribute name and data type as string parameters, can be used to parameterize attribute access. * `INSERT` *statements*: If you are using xref:querying:data-modification-statements.adoc#_insert_into_statement[`INSERT`] to add data to your graph, you need to specify what type of vertex or edge you want to add.This can also be parameterized. -The following example demonstrates Dynamic GSQL Query techniques using the xref:graph-ml:centrality-algorithms:pagerank.adoc[PageRank algorithm] from our Graph Data Science library. +The following example demonstrates Dynamic GSQL Query techniques using the xref:graph-ml:centrality-algorithms:pagerank.adoc[PageRank algorithm] from our Graph Data Science library. The query is written with schema information embedded statically in it: * graph name = social @@ -565,7 +568,7 @@ If a query is saved as a draft before it reaches valid status, any queries that ==== If a user creates a query, this user becomes the owner of this query automatically. -For a detailed description, please refer to xref:xref:tigergraph-server:user-access:fine-grained-query-privileges.adoc +For a detailed description, please refer to xref:{page-component-version}@tigergraph-server:user-access:fine-grained-query-privileges.adoc[] ==== == `INTERPRET QUERY` @@ -649,7 +652,7 @@ installQuery := INSTALL QUERY [installOptions] ( "*" | ALL | queryName ["," quer Required privilege: INSTALL_QUERY -`INSTALL QUERY` installs a query or multiple queries on a graph.Installing a query compiles the procedures described by the query as well as generates a xref:tigergraph-server:API:built-in-endpoints.adoc#_run_an_installed_query_get[REST endpoint] for running the query. +`INSTALL QUERY` installs a query or multiple queries on a graph.Installing a query compiles the procedures described by the query as well as generates a xref:{page-component-version}@tigergraph-server:API:built-in-endpoints.adoc#_run_an_installed_query_get[REST endpoint] for running the query. Installing a query allows the query to be run through the `RUN QUERY` command as well as through its REST endpoint, both offering stronger performance as compared to running the query through the `INTERPRET QUERY` command. The `INSTALL QUERY` command will install the queries specified, with query names separated by a comma. @@ -679,33 +682,37 @@ Concurrent `INSTALL QUERY` commands are allowed as long as only one `INSTALL QUE === Options -The following options are available: +`INSTALL QUERY` offers the following options: -[width=``100%'',cols=``19%,81%'',options=``header''] +[cols=",6", options="header"] |=== -|Option|Effect - -|`-FORCE` -|Re-installs the query even if the system indicates the -query is already installed. This is useful for overwriting an -installation that is corrupted or otherwise outdated, without having to -drop and then recreate the query. If this option is not used, the GSQL -shell will refuse to re-install a query that is already installed. -a|`-SINGLE` -|Enables a new internal framework for compiling non-distributed queries. Equivalent to the `single_gpr` session parameter described on the xref:ddl-and-loading:system-and-language-basics.adoc#_session_parameters[Session Parameters page.] - -The loop variable in a `xref:querying:control-flow-statements.adoc#_foreach_statement[FOREACH` loop] with this option enabled is treated as a copy, while normally, changes to the loop variable will change the value in the set or bag expression. +|Option|Effect -a|`-COST` -|Installs and optimizes the query using xref:query-optimizer/index.adoc[cost-based optimization]. +|`-COST` +a|Install and optimize the query using xref:query-optimizer/index.adoc[cost-based optimization]. The optimizer uses various statistics to generate an efficient traversal plan when compiling a query. You can benefit from this option if your query uses a `FROM` clause that uses a xref:select-statement/index.adoc#_path_pattern[path pattern]. -This option can be used together with other options, but it must come after the other options. +[NOTE] +==== +* This option can be used together with other options, but it must come after the other options. For example, you cannot run `INSTALL QUERY -COST -FORCE ALL`, it must be `INSTALL QUERY -FORCE -COST ALL` +* This is a *Preview feature* and should not be used in production. +==== + +|`-FORCE` +|Re-install the query even if the system indicates the +query is already installed. +This is useful for overwriting an installation that is corrupted or otherwise outdated. +If this option is not used, the GSQL shell will refuse to re-install a query that is already installed. + +|`-SINGLE` +a|Apply the same engine framework used for distributed queries, even on a single server. Equivalent to the `single_gpr` session parameter described at xref:ddl-and-loading:system-and-language-basics.adoc#_session_parameters[Session Parameters]. + +NOTE: This option treats the loop variable in a `xref:querying:control-flow-statements.adoc#_foreach_statement[FOREACH` loop] as a copy. +Updating the loop variable (copy) in the `FOREACH` block will not affect the actual loop variable. -This is a Preview feature and should not be used in production. |=== === Optimize installed queries @@ -726,7 +733,7 @@ The `RUN QUERY` command runs an installed query. To run a query with the `RUN QUERY` command, specify the query name, followed by the query parameters enclosed in parentheses. Running a query executes all statements in the query body and produces output as specified by the output statements in the query. -You can also run an installed query through REST requests - see xref:tigergraph-server:API:built-in-endpoints.adoc#_run_an_installed_query_get[Run an installed query]. +You can also run an installed query through REST requests - see xref:{page-component-version}@tigergraph-server:API:built-in-endpoints.adoc#_run_an_installed_query_get[Run an installed query]. === Syntax @@ -743,7 +750,7 @@ parmeterValueJSON ::= '{"'parameterName'":' parameterValue(', "'parameterName'": Required privilege: EXECUTE_QUERY -To learn more about the -queue option, please refer xref:tigergraph-server:system-management:workload-management.adoc#_running_a_query[Workload Management] +To learn more about the -queue option, please refer xref:{page-component-version}@tigergraph-server:system-management:workload-management.adoc#_running_a_query[Workload Management] === Query parameters @@ -752,7 +759,15 @@ There are two ways of passing parameters to a query in a `RUN QUERY` command: * link:#_parameter_list[Pass parameters as an ordered list separated by commas] * link:#_parameter_json_object[Pass parameters by name in JSON] -==== Parameter list +[NOTE] +==== +These rules are for running a query in the GSQL CLI. +Slightly different rules apply when running the query either with the xref:{page-component-version}@tigergraph-server:API:built-in-endpoints.adoc#_run_an_installed_query_post[RESTPP endpoint] or with the newer xref:{page-component-version}@tigergraph-server:API:gsql-endpoints.adoc#_run_query[GSQL endpoint]. + +==== + +[#_parameter_list] +==== Ordered list of Parameters To pass parameters to a query with a list, the parameters must be put in the same order as they were in the query definition. Each value passed in will correspond to the parameter at the same index when the query was created. @@ -807,9 +822,11 @@ GSQL > RUN QUERY greet_person(21) } ---- -==== Parameter JSON object +[#_parameter_json_object] +==== Parameters by name -To pass query parameters by name with a JSON object, map the parameter names to their values in a JSON object enclosed in parentheses. Parameters that are not named in the JSON object will keep their default values for the execution of the query. +Passing parameters as a JSON object has two advantages: they can be in any order, and you simply omit ones if you accept the default. +To pass query parameters by name, map the parameter names to their values in a JSON object enclosed in parentheses. Parameters that are not named in the JSON object will keep their default values for the execution of the query. For example, if we have the following query: @@ -825,7 +842,8 @@ Supplying the parameters with a JSON object will look like the following. The pa RUN QUERY greet_person( {"name": "Emma", "age": 21} ) ---- -=== Complex type parameter passing +[#_complex_type_parameter_passing] +=== Parameter format for complex types This subsection describes how to format the complex type parameter values when executing a query by `RUN QUERY`. @@ -833,11 +851,11 @@ More details about all parameter types are described in xref:data-types.adoc#_qu [NOTE] ==== -If a vertex type has a xref:ddl-and-loading:defining-a-graph-schema.adoc#_composite_keys[composite key], use a comma to separate the different attributes to denote their ID. +If a vertex type has a xref:ddl-and-loading:defining-a-graph-schema.adoc#_composite_key_using_primary_key[composite key], use a comma to separate the different attributes to denote their ID. For example, if you have the following vertex definition: -[.wrap,gsql] +[cols="2,3,3",.wrap,gsql] ---- CREATE VERTEX Composite_Person(id UINT, name STRING, age UINT, primary key (name, id)) ---- @@ -845,51 +863,73 @@ CREATE VERTEX Composite_Person(id UINT, name STRING, age UINT, primary key (name A vertex ID would be `"Tom,456"`, consisting of the `name` attribute and the `id` attribute. ==== -==== Parameter list +==== Values in a parameter List [width="100%",cols="28%,36%,36%",options="header",] |=== |Parameter type |Syntax |Example -|`DATETIME` |Use a string formatted as `"YYYY-MM-DD HH-MM-SS"` +|`DATETIME` |A string formatted as `"YYYY-MM-DD HH-MM-SS"` |`"2019-02-19 19:19:19"` -|Set or bag of primitives |Use square brackets to enclose the collection -of values. |A set of integers: `[1,5,10]` +|List/set/bag |Square brackets enclose a comma-separated list +of values. |A collection of integers: `[1,5,10]` -|Typed vertex parameter: `VERTEX` |If the vertex type is specified in the query -definition, then the vertex argument is `**vertex_id**` |The vertex type -is `Person` and the desired ID is `person2`. `"person2"` +|Map +|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 +a| An map: + +`{"keylist":[49,50], "valuelist":["Alaska","Hawaii"]}}` -|Generic vertex parameter: `VERTEX` |If the type is not defined in the -query definition, then the argument must be a tuple of strings with both the id and type: `("vertex_id", "vertex_type")` |A vertex with ID `person1` and -type `Person`: `("person1","Person")` +|Typed vertex parameter: `VERTEX` +|If the vertex type is specified in the query definition, +then the vertex argument is `**vertex_id**` +|The vertex type +is `Person` and the desired ID is `person2`. `"person2"` -|Set or bag of typed vertex parameters `VERTEX` |Same as a set or bag of primitives, where -the primitive type is the vertex ID. |`[ "person3", "person4" ]` +|Generic vertex parameter: `VERTEX` +|If the type is not defined in the query definition, then the argument must be +a tuple of strings with both the id and type: `("vertex_id", "vertex_type")` +|A vertex with ID `person1` and type `Person`: `("person1","Person")` -|Set or bag of generic `VERTEX` parameters |Same as a set or bag of -vertices, with vertex type not pre-specified. Square brackets enclose a -comma-separated list of vertex (id, type) tuples. Mixed types are -permitted. |`[ ("person1","Person"),("11","Post") ]` +|List/set/bag of generic `VERTEX` parameters +|Square brackets enclose a comma-separated list of vertex +(id, type) tuples. Mixed types are permitted. +|`[ ("person1","Person"),("11","Post") ]` |=== Queries that could take any vertex type as input should be written using generic `VERTEX` parameters. Users who call these queries will provide `("id", "type")` tuple arguments for these parameters. -==== Parameter JSON object +==== Values in parameter by name -[width="99%",cols="28%,36%,36%",options="header",] +Each parameter has the form `"":`. +The table below focuses on the part. + +[cols="2,3,3",options="header",] |=== -|Parameter type |Syntax |Example -|`DATETIME` |Use a string formatted as `"YYYY-MM-DD HH-MM-SS"` +|Parameter type |Syntax for Value |Example + +|`DATETIME` +|A string formatted as `"YYYY-MM-DD HH-MM-SS"` |`"2023-01-01 00:00:00"` -|Set or bag of primitives |Use a JSON array containing the primitive -values |`["a", "list", "of", "args"]` +|List/set/bag of primitives +|A JSON array containing the primitive values +|`["a", "list", "of", "args"]` + +|Map +|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 +a| An map: + +`{"keylist":[49,50], "valuelist":["Alaska","Hawaii"]}}` -|`VERTEX` (typed vertex parameter) |Since the type is already specified in the query, you only need to use a JSON object containing the field -`"id"` for the vertex ID |`{"id": "person1"}` +|`VERTEX` (typed vertex parameter) +|Since the type is already specified in the query, you only need +to use a JSON object containing the field `"id"` for the vertex ID +|`{"id": "person1"}` |`VERTEX` (generic vertex parameter) @@ -897,7 +937,7 @@ values |`["a", "list", "of", "args"]` vertex ID and a field `"type"` for the type of the vertex. |`{"id": "person1","type": "Person"}` -|Set or bag of `VERTEX` |Use a JSON array containing a list of +|List/set/bag of `VERTEX` |Use a JSON array containing a list of JSON `VERTEX` objects |`[{"id": "person1"}, {"id": "person2"}]` |=== @@ -928,7 +968,7 @@ Typically, the GSQL `RUN QUERY` command runs in the foreground and does not prod You can run queries in Detached Mode to enable background execution of long-running queries. -Queries executed in Detached mode are still subject to the system timeout limit. The default timeout limit is 16 seconds and can be set using the xref:tigergraph-server:API:index.adoc#_gsql_query_timeout[`GSQL-TIMEOUT`] header. +Queries executed in Detached mode are still subject to the system timeout limit. The default timeout limit is 16 seconds and can be set using the xref:{page-component-version}@tigergraph-server:API:index.adoc#_gsql_query_timeout[`GSQL-TIMEOUT`] header. To run a query in Detached Mode from the command line, use the``-async``option for the``RUN QUERY``command: @@ -937,14 +977,14 @@ To run a query in Detached Mode from the command line, use the``-async``option f GSQL > RUN QUERY -async ---- -You will receive a JSON response immediately containing a query ID (`request_id`): +You will receive a JSON response immediately containing a query ID (`requestid`): [source.wrap,json] ---- { "error": false, "message": "The query is successfully submitted. Please check query status using the request id.", - "request_id": "" + "requestid": "" } ---- @@ -955,8 +995,30 @@ To run queries in Detached Mode via RESTPP endpoint call, use the `GSQL-ASYNC` h $ curl -s -H "GSQL-ASYNC:true" GET "http://localhost:14240/restpp/query//?parameter1= ---- -To check the status and results of the queries executed in Detached Mode, use the xref:tigergraph-server:API:built-in-endpoints.adoc#_check_query_status_detached_mode[*`/query_status`*] and the xref:tigergraph-server:API:built-in-endpoints.adoc#_check_query_results_detached_mode[*`/query_result`*] RESTPP endpoints. +To check the status and results of the queries executed in Detached Mode, use the xref:{page-component-version}@tigergraph-server:API:built-in-endpoints.adoc#_check_query_status_detached_mode[*`/query_status`*] and the xref:{page-component-version}@tigergraph-server:API:built-in-endpoints.adoc#_check_query_results_detached_mode[*`/query_result`*] RESTPP endpoints. + +==== Query Profiling -profile Option + +The `-PROFILE` option allows you to activate xref:{page-component-version}@gsql-ref:querying:query-optimizer/query-profiling.adoc#_gsql[query profiling] when running a query in GSQL. Currently, the only supported value for profiling is `BASIC`, which enables basic query profiling to view and analyze execution details. +By default, this option is empty, and profiling is not activated. + +*Example 1: Run query with profiling activated* + +[source,gsql] +---- +RUN QUERY -PROFILE BASIC +---- + +*Example 2: Run query in async mode with profiling activated* + +[source,gsql] +---- +RUN QUERY -ASYNC -PROFILE BASIC +---- +You can also use the `-PROFILE` option with the `-async` option to run the query asynchronously and retrieve real-time profiling data. +This is useful for long-running queries where you need to monitor the execution while the query is still running. +Once the query is submitted, you can use the `/query_status` API to get profiling data for that query. == GSQL Query output format @@ -1246,7 +1308,7 @@ GSQL > SHOW DESCRIPTION OF QUERY_PARAM query2.* === Drop description -The `DROP DESCRIPTION` removes descriptions of queries or query parameters. +The `DROP DESCRIPTION` removes descriptions of queries or query parameters. *Syntax* [source] @@ -1255,12 +1317,12 @@ DROP DESCRIPTION OF [ON GRAPH ] ---- * `` can include a comma-separated list of names. -* For the `DROP DESCRIPTION` command, you can specify multiple queries or parameters in a single command using a comma-separated list. +* For the `DROP DESCRIPTION` command, you can specify multiple queries or parameters in a single command using a comma-separated list. Required privilege `WRITE_QUERY` -To remove a description, run the `DROP DESCRIPTION` command as shown below. +To remove a description, run the `DROP DESCRIPTION` command as shown below. [source, gsql] ---- @@ -1279,9 +1341,9 @@ Therefore, after dropping the query description, the query parameter's descripti [NOTE] ==== -* *Wildcards:* +* *Wildcards:* SHOW supports `\*` to both queries and parameters, while DROP only supports `*` to remove descriptions of all queries or parameters. -* *List of Objects:* +* *List of Objects:* SHOW cannot specify multiple objects in a comma-separated list, whereas DROP can. ==== diff --git a/modules/querying/pages/query-optimizer/enable-cost-optimizer.adoc b/modules/querying/pages/query-optimizer/enable-cost-optimizer.adoc index a66e36aa..27b3fde0 100644 --- a/modules/querying/pages/query-optimizer/enable-cost-optimizer.adoc +++ b/modules/querying/pages/query-optimizer/enable-cost-optimizer.adoc @@ -1,4 +1,4 @@ -= Enabling Cost-Based Optimization (Preview Feature) += Enabling Cost-Based Optimization :sectnums: :description: Steps to enable the query optimizer. @@ -118,7 +118,7 @@ To use the cost-based optimization during installation, use the xref:query-opera For example, to install the query `example3`, run `INSTALL QUERY -COST example3`. -Alternatively, set xref:basics:system-and-language-basics.adoc#_session_parameters[the `cost_opt` session parameter] to true by running `set cost_opt = true` in the GSQL shell. +Alternatively, set xref:basics:running-gsql.adoc#_session_parameters[the `cost_opt` session parameter] to true by running `set cost_opt = true` in the GSQL shell. This enables cost-based optimization for the rest of your GSQL session. You no longer need to supply the `-COST` option when installing queries if the `cost_opt` parameter is set to true. diff --git a/modules/querying/pages/query-optimizer/index.adoc b/modules/querying/pages/query-optimizer/index.adoc index dd891cba..b120b55c 100644 --- a/modules/querying/pages/query-optimizer/index.adoc +++ b/modules/querying/pages/query-optimizer/index.adoc @@ -1,9 +1,9 @@ -= Query Optimizer (Preview Feature) += Query Optimizer (Preview) :description: Overview of the query optimizer. The query optimizer optimizes the execution plan of a query. -When writing a GSQL query with multi-hop `SELECT` statements, the xref:querying:select-statement/index.adoc#_path_pattern[path pattern (Syntax V2)] specified in the `FROM` clause is declarative. +When writing a GSQL query with multi-hop `SELECT` statements, the xref:querying:select-statement/from-clause-v2.adoc#_path_pattern[path pattern (Syntax V2)] specified in the `FROM` clause is declarative. In other words, it specifies the structure of paths to be matched, without specifying the particulars of how the graph is traversed to find these paths. It is the query optimizer's job to determine the best graph traversal plan to satisfy the query. diff --git a/modules/querying/pages/query-optimizer/query-plan-cache.adoc b/modules/querying/pages/query-optimizer/query-plan-cache.adoc new file mode 100644 index 00000000..543f6311 --- /dev/null +++ b/modules/querying/pages/query-optimizer/query-plan-cache.adoc @@ -0,0 +1,59 @@ += Query Plan Cache + +This page covers how TigerGraph handles query execution and optimization through query plan caching. +When a query is executed, the system parses, transforms, and optimizes it before generating a query plan in JSON format to guide its execution. +While these steps are essential for processing the query, they can introduce significant overhead, especially when the same query is executed multiple times. +To mitigate this, TigerGraph caches the generated query plan in memory, ensuring faster execution on subsequent executions of a query. + +== Query Normalization + +In many cases, users may frequently change constants in their queries. These changes would invalidate the cached query plan, making it necessary to re-interpret the query. +To avoid the reinterpretation, TigerGraph employs a process known as *query normalization*. + +Query normalization helps maintain the validity of the cached query plan even when constants in the query change. Here's how it works: + +. *Extract Constants*: TigerGraph identifies and extracts constants from the query. For example, values like specific numbers or strings in the WHERE clause are identified as constants. + +. *Bind Variables*: The extracted constants are replaced with query parameters. This ensures that even if the constant values change, the query text itself remains unchanged. + +. *Cache the Normalized Query Plan*: The normalized query plan is cached, and since the text of the query doesn't change (only the constants are replaced with parameters), the plan remains valid even when the constants change. + +== Example of Query Normalization + +[source.wrap,gsql] +---- +INTERPRET QUERY () { + L = SELECT s + FROM Person:s + WHERE s.id >= 100 AND s.lastName == "Wang" + ; + R = SELECT t + FROM L:s -(LIKES>:e)- Comment:t + WHERE e.creationDate >= "1982-02-06 00:00:00" AND t.id >= 1200; + PRINT R.size() AS result_size; +} +---- + +In the example above, the query has constants like `100` and `"Wang"`, which are likely to change over time. +After normalization, the query would look like this: + +[source.wrap,gsql] +---- +INTERPRET QUERY (INT GSQL_p1, STRING GSQL_p2, STRING GSQL_p3, INT GSQL_p4) { + L = SELECT s + FROM Person:s + WHERE s.id >= GSQL_p1 AND s.lastName == GSQL_p2; + R = SELECT t + FROM L:s -(LIKES>:e)- Comment:t + WHERE e.creationDate >= GSQL_p3 AND t.id >= GSQL_p4; + PRINT R.size() AS result_size; +} +---- + +Here, the constants `100`, `"Wang"`, `"1982-02-06 00:00:00"`, and `1200` have been replaced with query parameters (`GSQL_p1`, `GSQL_p2`, `GSQL_p3`, `GSQL_p4`). +This allows the query plan to remain valid even if the values of these constants change in future executions. + +There are two key xref:{page-component-version}@tigergraph-server:reference:configuration-parameters.adoc#gsql[configuration parameters] available to customize the query plan cache. +The `GSQL.QueryPlanCache.Enable` parameter enables the query plan cache, with the default value set to `true`. This ensures that query plans are cached to improve performance. +Additionally, the `GSQL.QueryPlanCache.Capacity` parameter defines the maximum number of queries that can be stored in the cache, with a default value of `10,000`. +This capacity can be adjusted within the range of 1 to 100,000, depending on your system’s requirements. diff --git a/modules/querying/pages/query-optimizer/query-profiling.adoc b/modules/querying/pages/query-optimizer/query-profiling.adoc new file mode 100644 index 00000000..cc7d3ce3 --- /dev/null +++ b/modules/querying/pages/query-optimizer/query-profiling.adoc @@ -0,0 +1,457 @@ += Query Profiling +:description: Query Profiling provides data to analyze the details of a query execution. +:toc: +:toclevels: 1 + +This page provides an overview of query profiling in TigerGraph, a feature introduced in version 4.2. +Query profiling allows users to view detailed metrics and data about a query's execution, whether it is running or completed. +By analyzing query profiling data, users can identify performance bottlenecks, troubleshoot issues, and optimize queries for better performance. + +== Introduction + +Query profiling is designed to provide insights into query execution, allowing users to examine the performance of a query in real-time or after completion. This data helps identify potential areas for optimization and diagnose performance issues. +You can use query profiling to gain visibility into execution times, memory usage, and the number of vertices and edges accessed during query processing. + +== Supported Scope and Limitations + +This feature applies only to GSQL syntax and is not supported for OpenCypher syntax at this time. + +=== Supported Query Types + +Query profiling is supported for the following types of queries: + +* Installed *DISTRIBUTED* user-defined queries +* Installed *NON-DISTRIBUTED* user-defined queries, if installed with the `-SINGLE` flag (e.g., `INSTALL QUERY -SINGLE q1`) +* Three built-in endpoints: +** `/kstep_expansion` +** `/allpaths` +** `/searchvertex` + +For these queries, profiling data will include more detailed information about memory usage and the overall query execution, as explained in the xref:{page-component-version}@gsql-ref:querying:query-optimizer/query-profiling.adoc#_profiling_data_explanation[Profiling Data Explanation] section below. + +=== Limitations + +While query profiling is a powerful tool for diagnosing and optimizing query performance, there are some limitations: + +* It does not support OpenCypher syntax. +* It does not support `INTERPRET` queries. +* It is not available for non-distributed queries unless installed with the `-SINGLE` flag. +* Profiling does not include data for subqueries. +* Memory metrics do not account for edge and global accumulators. +* Topology metrics do not include attribute data. +* Profiling does not track create/update/delete operations in the topology metric. + +== Prerequisite + +To enable query profiling, users must have the READ QUERY or OWNERSHIP privileges for the query being executed. +If RESTPP authentication is enabled, users will need to ensure they have the appropriate privileges. +Otherwise, they may encounter an error message like this: + +[source,json] +---- +{ + "version": { + "edition": "enterprise", + "api": "v2", + "schema": 1 + }, + "error": true, + "message": "Insufficient permissions to enable profiling on this request.", + "required_privileges": { + "Query Privileges": { + "GRAPHS": { + "SocialNet": { + "QUERIES": { + "qTest": { + "QUERY-LEVEL Privileges": [ + "READ [MISSING]" + ] + } + } + } + } + } + }, + "code": "REST-15001" +} +---- + +== How to Activate Profiling + +Activate profiling by setting a profiling mode. Currently, only one profiling mode, `BASIC`, is available. +You can choose the appropriate method from the options below based on whether you need real-time profiling or asynchronous query execution. + +=== RESTPP Request + +*Option 1: Run the query in the foreground*: + +To run a query and view the profile information in real-time, add the `PROFILE: BASIC` header to your RESTPP request: + +[source.wrap,bash] +---- +curl -H "PROFILE: BASIC" -X POST 'http://localhost:14240/restpp/query/testGraph/{query_name}' +---- + +*Option 2: Run the query asynchronously*: + +To run a query asynchronously with profiling enabled, add both the `GSQL-ASYNC: true` and `PROFILE: BASIC` headers to your request: + +[source.wrap,bash] +---- +curl -H "GSQL-ASYNC: true" -H "PROFILE: BASIC" -X GET 'http://localhost:14240/restpp/query/testGraph/{query_name}' +---- + +To fetch real-time profiling data for a query running in asynchronous mode, use the `/query_status` endpoint: + +[source.wrap,bash] +---- +curl -X GET "http://localhost:14240/restpp/query_status?requestid=$reqid" +---- + +=== GSQL + +*Option 1: Run the query in the foreground*: + +To run a query and view the profile information in real-time, using the `-PROFILE` flag followed by a profiling mode (e.g. `BASIC`): + +[source, gsql] +---- +RUN QUERY -PROFILE BASIC +---- + +*Option 2: Run the query asynchronously*: + +To run a query asynchronously with profiling enabled, also include the `-async` flag: + +[source, gsql] +---- +RUN QUERY -async -PROFILE BASIC +---- + +To fetch real-time profiling data for a query running in asynchronous mode, use the `/query_status` endpoint: + +[source.wrap,bash] +---- +curl -X GET "http://localhost:14240/restpp/query_status?requestid=$reqid" +---- + +*Option 3: Set profiling for the session*: + +You can set the profiling mode for a session in GSQL. Use the `SET PROFILE` command to enable profiling in your session: + +[source, gsql] +---- +SET PROFILE = "BASIC" +RUN QUERY +---- + +== Profiling Data Explanation + +When profiling is activated, the query result JSON and the `/query_status` output for real-time profiling will include a field called `profile`, which contains the profiling data. + +=== Profile Query Stages Breakdown + +To understand the query profiling stages, consider the following simple example: + +[source, gsql] +---- +CREATE DISTRIBUTED QUERY qTest(INT temp) { + INT threshold = 90; // statementKey 1 (1 action) + IF temp > threshold THEN // statementKey 2 (2 child statements) + STRING new_state = "sweat"; // statementKey 2.1 (1 action) + vSet = SELECT s from person:s // statementKey 2.2 (3 actions: create_vset, vertex, reduce) + POST-ACCUM s.state = new_state; + END; +} +---- + +The execution of this query `qTest` can be broken down into the following stages: + +* *Scheduling*: The stage between when TigerGraph receives the request and assigns a thread to process it. +* *Execution*: This stage includes several sub-stages: +** *Initialization*: Initializes global variables and starts workers on all nodes for distributed queries. +** *Processing*: The main logic of the query, including control flow, graph traversal, and data processing. +** *Finalization*: Constructs and sends the query result. + +Within the *Processing* stage, there are two types of fine-grained stages: + +* *Statement*: Represents a complete statement in the original query (e.g., graph traversal, control-flow). +* *Action*: Represents the smallest unit of execution in the final query plan. A statement without child statements will have child actions, while a statement with child statements will not have child actions. + +=== General Metrics + +Query profiling includes several general metrics at different levels (Query, Statement, and Action). Some of the key metrics are: + +==== ExecutionCount + +This metric indicates how many times a particular stage has been executed and completed. It does not count stages that are currently in progress. + +==== Time + +The time metric provides the following data: + +* *startTime*: The start time of the stage. +* *endTime*: The end time of the stage. + +[NOTE] +==== +If the execution count is greater than 1, the *startTime* and *endTime* fields will not be provided. +==== + +==== Memory + +The memory metric tracks memory usage across different GPE nodes. +It includes data for `vertexAccumulator` memory, which represents memory used by vertex-attached accumulators. + +Notice the vertexAccumulator include internal variables not explicitly declared in original query, so it can be non-zero even there’s no VERTEX-attached accumulators declared. + +Key memory fields: + +* *totalPeakMB*: Peak memory usage during the stage execution. +* *totalFinalMB*: Memory usage at the end of the stage. + +==== Topology + +Data for this metric is separated to different GPE nodes, with name in format `GPE__`. + +For each GPE node, this metric contains non-zeros values for following fields: + +* `vertex` +** `readCount`: The number of accesses to vertices. + +* `edge` +** `readCount`: The number of accesses to edges. + +* `table` +** `rowCount`: The number of accesses to table rows. + +* `join` +** `totalCount`: The total number of join operations. + +=== Profiling Data Hierarchy + +Profiling data is organized in three hierarchical levels: Query, Statement, and Action. +Each level provides additional details about the query execution. + +==== Query Level + +This is for field `profile.overall`. It may contain the following extra fields. + +* `runningActionKey`: current on-going action. It only appears before query completes. +* `time` +** `scheduling` +*** `schedulingTimeMs`: time spent on “Scheduling” +*** `schedulingTimePercentage`: percentage of `schedulingTimeMs` to the `totalTimeMs`. +** `execution` +*** `initialization` +**** `initializationTimeMs`: time spent on “Initialization” +**** `initializationTimePercentage`: percentage of `initializationTimeMs` to the `totalTimeMs`. +*** `processing` +**** `processingTimeMs`: time spent on “Processing” +**** `processingTimePercentage`: percentage of `processingTimeMs` to the `totalTimeMs`. +*** `finalization` +**** `finalizationTimeMs`: time spent on “Finalization” +**** `finalizationTimePercentage`: percentage of `finalizationTimeMs` to the `totalTimeMs`. +** `totalTimeMs`: total time of query run, including “Scheduling” and “Execution”. + +==== Statement Level + +Element in `profile.statements` are statement-level entries. +A statement-level entry can also contain child statements. Each statement-level entry represents a statement in the original query. +It may contain the following extra fields: + +* `statementKey`: this is unique key for this statement in the original query. +* `statementType`: type of this statement in the original query. +* `statementText`: text of this statement in the original query. +* `statementOverall` +** `time` +*** `processingTimeMs`: time spent on this statement, including all executions. +*** `processingTimePercentage`: percentage of `processingTimeMs` to query-level `totalTimeMs`. +*** `averageProcessingTimeMs`: average process time of each execution. It only appears when `executionCount > 1`. +* `statements`: child statement entries of this statement. +* `actions`: child action entries of this statement. + +==== Action Level + +Elements in `actions` of statement-level entry are action-level entries. +Each action-level entry represents a minimum execution unit in execution plan, from final transformed and optimized query. +It may contain the following extra fields: + +* `actionKey`: this is unique key for this action. +* `actionType`: type of this action in the final transformed query. +* `actionText`: text of this action in the final transformed query. +* `actionOverall` +** `time` +*** `processingTimeMs`: time spent on this action, including all executions. +*** `processingTimePercentage`: percentage of `processingTimeMs` to query-level `totalTimeMs`. +*** `averageProcessingTimeMs`: average process time of each execution. It only appears when `executionCount > 1`. + +== Disable Query Profiling + +If the Query Profiling feature is causing issues, it can be disabled for all installed queries by following this procedure: + +1. Add `DISABLE_PROFILE=true;` to the `GSQL.BasicConfig.Env` xref:{page-component-version}@tigergraph-server:reference:configuration-parameters.adoc[configuration parameter]. + +2. Apply the change: `gadmin config apply` + +3. Re-installing all queries. + +== Profiling Data Example + +=== Example of Profiling Data for Finished Request + +Below is an example final result for a request of query `qTest`, with profiling enabled. It’s running on a 2x1 cluster. + +[source,json] +---- +{ + "version": { + "edition": "enterprise", + "api": "v2", + "schema": 0 + }, + "error": false, + "message": "", + "results": [], + "profile": { + "queryName": "qTest", + "requestId": "16973826.RESTPP_1_1.1742242555505.N", + "serverId": "GPE_1_1", + "overall": { + "executionCount": 1, + "time": { + "startTime": "2025-03-17 20:15:55.505 UTC", + "endTime": "2025-03-17 20:16:02.420 UTC", + "totalTimeMs": 6915, + "scheduling": { + "schedulingTimeMs": 1, + "schedulingTimePercentage": 0.0145 + }, + "execution": { + "executionTimeMs": 6914, + "executionTimePercentage": 100, + "initialization": { + "initializationTimeMs": 4, + "initializationTimePercentage": 0.0578 + }, + "processing": { + "processingTimeMs": 6910, + "processingTimePercentage": 99.9 + }, + "finalization": { + "finalizationTimeMs": 0, + "finalizationTimePercentage": 0 + } + } + }, + "memory": { + "GPE_2_1": { + "vertexAccumulator": { + "totalPeakMB": 23, + "totalFinalMB": 21 + } + }, + "GPE_1_1": { + "vertexAccumulator": { + "totalPeakMB": 23, + "totalFinalMB": 21 + } + } + }, + "topology": { + "GPE_2_1": { + "vertex": { + "readCount": 12360296 + } + }, + "GPE_1_1": { + "vertex": { + "readCount": 12368774 + } + } + } + }, + "statements": [....] // Nested statement, details not showm + } + ] + } +} +---- + +=== Example of Realtime Profiling Data for Running Request + +Below is an example output of `/query_status` for an async request of query `qTest`, with profiling enabled, running on a 2x1 cluster. +You can notice this field `"runningActionKey": "2.2.3"`, which indicates the current running action. And there’s not much profiling data in `"actionOverall"` for `"actionKey": "2.2.3"`, except for the `"startTime"`. + +[source,json] +---- +{ + "version": { + "edition": "enterprise", + "api": "v2", + "schema": 0 + }, + "error": false, + "message": "", + "results": [ + { + "requestid": "16973827.RESTPP_1_1.1742242692587.N", + "startTime": "2025-03-17 20:18:12.587", + "expirationTime": "2025-03-17 20:18:28.587", + "url": "/query/SocialNet/qTest?temp=93", + "elapsedTime": 1137, + "status": "running", + "user": "", + "profile": { + "queryName": "qTest", + "requestId": "16973827.RESTPP_1_1.1742242692587.N", + "serverId": "GPE_2_1", + "overall": { + "executionCount": 0, + "runningActionKey": "2.2.3", + "time": { + "startTime": "2025-03-17 20:18:12.583 UTC", + "scheduling": { + "schedulingTimeMs": 0 + }, + "execution": { + "initialization": { + "initializationTimeMs": 4 + }, + "processing": {} + } + }, + "memory": { + "GPE_1_1": { + "vertexAccumulator": { + "totalPeakMB": 24, + "totalFinalMB": 21 + } + }, + "GPE_2_1": { + "vertexAccumulator": { + "totalPeakMB": 23, + "totalFinalMB": 21 + } + } + }, + "topology": { + "GPE_1_1": { + "vertex": { + "readCount": 6184387 + } + }, + "GPE_2_1": { + "vertex": { + "readCount": 6180148 + } + } + } + }, + "statements": [....] // Nested statement, details not showm + } + } + ], + "code": "REST-0000" +} +---- diff --git a/modules/querying/pages/query-optimizer/stats-api.adoc b/modules/querying/pages/query-optimizer/stats-api.adoc index f85280ec..c9ed71ad 100644 --- a/modules/querying/pages/query-optimizer/stats-api.adoc +++ b/modules/querying/pages/query-optimizer/stats-api.adoc @@ -1,4 +1,4 @@ -= Statistics REST APIs (Preview Feature) += Statistics REST APIs The endpoints on this page calculate cardinality and histogram statistics of vertex and edge types and attributes. The statistics are required for effective optimization. diff --git a/modules/querying/pages/select-statement/from-clause-v2.adoc b/modules/querying/pages/select-statement/from-clause-v2.adoc new file mode 100644 index 00000000..af07ae04 --- /dev/null +++ b/modules/querying/pages/select-statement/from-clause-v2.adoc @@ -0,0 +1,374 @@ += FROM Clause (Syntax V2) +:navtitle: From Clause (V2) + +The FROM clause in GSQL Syntax V2 is used to define path patterns for traversing the graph structure. +A path pattern specifies how vertices and edges are connected and provides the basis for the query to traverse the graph. +In V2, the FROM clause supports both traditional vertex-edge patterns and more advanced multi-hop patterns. + +This page will focus on V2 syntax, which is an evolution of the V1 syntax, with improved flexibility and support for more complex graph traversals. +While GSQL still supports the V1 syntax, we will describe the V2 style here, including examples of how to use path patterns and multiple path patterns for more complex graph queries. + + +[#_from_clause] +== `FROM` + +.`FROM` clause +[source,ebnf] +---- +fromClauseV1 := FROM step +fromClauseV2 := FROM stepV2 | pathPattern ["," pathPattern]*) +fromClause := fromClauseV1 | fromClauseV2 +---- + +A hop or step consists of going from a starting set of vertices, crossing over a set of their edges, to an ending set of vertices. +We typically use the names Source and Target for the starting and ending vertex sets: `Source -(Edges)-> Target` + +[#_path_pattern] +== Path pattern + +A path pattern specifies sets of vertex types and how they are connected by edge types. + +A path pattern starts with a source vertex set, traverses through specified path edge patterns to another step vertex set. +This is called a _hop_. +From the other step vertex set, it can perform multiple hops and traverse to other step vertex sets. + +Notice that a path pattern can be just a single source vertex set; the subsequent path edge pattern and step vertex sets are optional. + +.EBNF for path pattern +[source,ebnf] +---- +pathPattern := sourceVertexSet ["-" "(" pathEdgePattern ")" "-" stepVertexSet]* +---- + +[#_source_vertex_set] +=== Source vertex set +The source vertex set is the vertex set from which a path pattern starts. +A source vertex set can be denoted by one of the following: + +* `_` or `ANY`, or omitted. +If the source vertex type is omitted, you must give the source vertex set an <<_vertex_and_edge_aliases,alias>>. +* Vertex type +* A vertex set variable + +Optionally, you can give a source vertex set an alias by appending the alias after a colon``:``. +Although declaring an alias is optional, it is strongly recommended that you declare them. +In the later clauses of the `SELECT` block , you can only refer to vertex sets in the `FROM` clause by their aliases. + +.EBNF for source vertex set +[,ebnf] +---- +sourceVertexSet := [sourceVertexTypes] [":" vertexAlias] +sourceVertexTypes := "_" | ANY | "(" sourceVertexSetType ["|" sourceVertexSetType]* ")" +sourceVertexSetType := vertexType | vertexSetVariableName +---- + +Belows are a few examples of valid source vertex sets in `SELECT` statements: + +[tabs] +==== +Vertex type:: ++ +-- +[.wrap,gsql] +---- +Result = SELECT src + FROM Person:src -( + WHERE src.first_name == "Viktor" AND src.last_name == "Akhiezer" + ACCUM CASE + WHEN tgt.type == "Comment" THEN + src.@comment_cnt += 1 + WHEN tgt.type == "Post" THEN + src.@post_cnt += 1 + END; +---- +<1> `Person` is a vertex type. +`(Comment | POST)` combines two vertex types. +-- +Any type:: ++ +-- +You can use `_` or `ANY` to represent any vertex types. +You can also choose to omit the step vertex type altogether to represent any vertex type. +If you choose to omit the type, you must give the step vertex set an alias. + +[.wrap,gsql] +---- +Result = SELECT tgt + FROM :s -(>, step vertex sets have more flexibility in how they are denoted. +A step vertex set can be denoted by one of the following: + +* `_` or `ANY`, or omitted. +If the step vertex type is omitted, you must give the step vertex set an alias. +* Vertex type +* A vertex set variable +* A global accumulator + +Optionally, you can give a source vertex set an alias by appending the alias after a colon``:``. +Although declaring an alias is optional, TigerGraph strongly suggests that you declare them. +In the later clauses of the `SELECT` block , you can only refer to vertex sets in the `FROM` clause by their aliases. + + +.EBNF for step vertex set +[.wrap,ebnf] +---- +stepVertexSet := [stepVertexTypes] [":" vertexAlias] +stepVertexTypes := atomicVertexType | "(" vertexSetType ["|" vertexSetType]* ")" +atomicVertexType := "_" | ANY | vertexSetType +vertexSetType := vertexType | vertexSetVariableName | globalAccumName +---- + +Belows are a few examples of valid step vertex sets in `SELECT` statements: + +[tabs] +==== +Vertex type:: ++ +-- +[.wrap,gsql] +---- +Result = SELECT tgt + FROM Person:tgt -( + WHERE tgt.firstName == "Viktor" AND tgt.lastName == "Akhiezer" + ACCUM CASE + WHEN src.type == "Comment" THEN + tgt.@commentCnt += 1 + WHEN src.type == "Post" THEN + tgt.@postCnt += 1 + END; +---- +<1> `Person` is a vertex type. +`(Comment | POST)` combines two vertex types. +-- +Any type:: ++ +-- +You can use `_` or `ANY` to represent any vertex types. +You can also choose to omit the step vertex type altogether to represent any vertex type. +If you choose to omit the type, you must give the step vertex set an alias. + +[.wrap,gsql] +---- +Result = SELECT s + FROM Person:s -(Likes>)- :tgt + WHERE s.first_name == "Viktor" AND s.last_name == "Akhiezer" +---- +-- +Vertex set:: ++ +-- +A step vertex set can also be represented by a vertex set variable. +[.wrap,gsql] +---- +include::appendix:example$friend_net/select_statement_index_step_vertex_set.gsql[] +---- +-- +Global accumulator:: ++ +-- +A step vertex set can be represented by a global accumulator of strings (the strings are vertex types). +The accumulator must be of type `SetAccum`, `BagAccum` or `ListAccum`. + +[.wrap,gsql] +---- +include::appendix:example$friend_net/select_statement_index_step_vertex_global_accumulator.gsql[] +---- +-- +==== + +=== Path edge pattern +The path edge pattern represents the relationship between a source vertex set to a step vertex set or from a step vertex set to the next step vertex set. + +.EBNF for path edge pattern +---- +pathEdgePattern := atomicEdgePattern + | "(" pathEdgePattern ")" + | pathEdgePattern "." pathEdgePattern + | disjPattern + | starPattern + +atomicEdgePattern := atomicEdgeType + | atomicEdgeType ">" + | "<" atomicEdgeType + +atomicEdgeType := "_" | ANY | edgeSetType + +disjPattern := atomicEdgePattern ("|" atomicEdgePattern)* + +starPattern := ([atomicEdgePattern] | "(" disjPattern ")") "*" [starBounds] + +starBounds := CONST_INT ".." CONST_INT + | CONST_INT ".." + | ".." CONST_INT + | CONST_INT +---- + +A path edge pattern can represent one hop or repeated hops. +A path edge pattern is denoted by `-()-`, where the relationship between vertex sets is specified between the parentheses. + +[discrete] +=== Atomic edge pattern + +The most basic form for a path edge pattern is an atomic edge pattern. +An atomic edge pattern can be one of the following: + +* `_` or `ANY`. +* An edge type. +* A string parameter. +The value of the parameter must be an edge type and can be provided at runtime. +You do not need to specify a direction when using a string parameter to specify the edge type. +* A global `SetAccum` accumulator of strings. +Each string is the name of an edge type. + +If the edge is directed, an atomic edge pattern has either a left pointer `<` on the left or a right pointer `>` on the right to indicate edge direction. +If the edge is undirected, the atomic edge pattern does not have a pointer. +Suppose we have 3 edge types or parameters called A, B, C. + +* `A>` is a rightward facing A edge +* `)-` refers to forward traversal of the directed edge type `STUDY_AT`. +* `-()-`. +* `-(KNOWS)-` refers to forward traversal of the undirected `KNOWS`. +* `-(_>)-` refers to forward traversal of any directed edge types. +* `-(_)-` refers to forward traversal of any undirected edge types. +* `-(<_)-` refers to backward traversal of any directed edge types. + +[discrete] +=== Disjunction pattern +Pattern disjunction allows a path edge pattern to indicate an `OR` relationship between two or more atomic patterns. +If an edge matches any of the atomic patterns, the edge matches the path edge pattern. + +.EBNF for disjunction pattern +[,ebnf] +---- +disjPattern := atomicEdgePattern ("|" atomicEdgePattern)* +---- + +For example: + +* `-(KNOWS|STUDY_AT>)-` refers to traversing an undirected `KNOWS` edge or a directed `STUDY_AT` edge. +* `-(KNOWS|_>)-` refers to traversing an undirected `KNOWS` edge or any directed edge from left to right. + + +=== Pattern repetition +The Kleene star``*`` and `min..max` range specifiers repeat an edge pattern for a specified number of times. +The range specifiers must be integers and must be constants. +See xref:tutorials:pattern-matching/repeating-a-pattern.adoc[] for a tutorial on how to use pattern repetition in a path edge pattern. + +.EBNF for star pattern +[,ebnf] +---- +starPattern := ([atomicEdgePattern] | "(" disjPattern ")") "*" [starBounds] + +starBounds := CONST_INT ".." CONST_INT + | CONST_INT ".." + | ".." CONST_INT + | CONST_INT +---- + +* Add `*` to the end of a pattern to have the star pattern match all paths where the edge pattern occurs one or more times. +** For example, `Person:s - (Friendship*) - Person` matches all paths between two `Person` vertices connected by any number of `Friendship` edges. +** The vertices in the middle do not need to be `Person` vertices. +For example, a path like `person1 -(Friendship)- dog1 - (Friendship) - person2` matches the star pattern. +* Add `*` to the end of a pattern, and then a number after the star to have the star pattern match paths where the edge pattern occurs for the specified number of times. +** For example, `Person:s - (Friendship*2) - Person` matches all paths between two `Person` vertices connected by exactly two `Friendship` edges. +The vertices in the middle do not need to be `Person` vertices. +* Add `*` to the end of a pattern, and then a range after the star (`*x..y`) to have the star pattern match all paths where the edge pattern occurs as many times as within the specified range. +** For example, `Employee:s - (Works_For>*2..4) - Employee` matches all paths between two `Employee` vertices with 2 - 4 right-directed `Works_For` edges. +The vertices in the middle do not need to be `Person` vertices. + +=== Pattern concatenation +The dot operator``.`` means concatenate the two edge patterns into one. +The vertex joining the two edges is omitted from the syntax. +The dot operator is a shorthand, when you don’t care about the type of that intermediate vertex. +`(A>.:e2)- Y:y -( + + +SELECT u +FROM X:x -(E2>. +---- +<1> This `FROM` clauses uses a longer pattern, but gives you access to `y`, `e2`, `z` and `e4`. +<2> This `FROM` clauses is more concise than the first `FROM` clause, but does not give you access to the intermediate vertex and edge sets. + +=== Conjunctive Pattern Matching + +The optional repeating phrase `["," pathPattern]*` allows you to have multiple path patterns. +They form a conjunction, meaning all of them must be satisfied in order to have a valid match result. +See xref:tutorials:pattern-matching/adv/conjunctive-pattern-matching.adoc[] for more details. + +[source,ebnf] +---- +fromClause := FROM (step | stepV2 | pathPattern ["," pathPattern]*) +---- + +Each step pattern or path pattern forms a match table, one row per matching path in the graph. +Each vertex alias or edge alias is one column in the table. +When we have a conjunctive path, each path must share at least one vertex alias with another path. +This enables the two path sets (and match tables) to be joined. +Formally, we make the natural join of the two tables. + + +[#_vertex_and_edge_aliases] +== Vertex and Edge Aliases + +Vertex and edge _aliases_ are declared within the `FROM` clause of a `SELECT` block, by using the colon `:`, followed by the alias name. +Aliases can be accessed anywhere within the same `SELECT` block. +They are used to reference a single selected vertex or edge of a set. +It is through the vertex or edge aliases that the attributes of these vertices or edges can be accessed. + +For example, the following code snippets show two different `SELECT` statements. +The first `SELECT` statement starts from a vertex set called `allVertices`, and the vertex alias name `v` can access each individual vertex from `allVertices`. +The second `SELECT` statement selects a set of edges.It can use the vertex alias `s` to reference the source vertices, or the alias `t` to reference the target vertices. + +.Vertex variables +[source,gsql] +---- +results = SELECT v FROM all_vertices:v; +results = SELECT t FROM all_vertices:s -()- :t; +---- + +The following example shows an edge-based `SELECT` statement, declaring aliases for all three parts of the edge. +In the `ACCUM` clause, the `e` and `t` aliases are assigned to local vertex and edge variables. + +.Edge variables +[source,gsql] +---- +results = SELECT v + FROM all_vertices:s -(:e)- :t + ACCUM VERTEX v = t, EDGE eg = e; +---- + +[WARNING] +==== +We strongly suggest that an alias should be declared with every vertex and edge in the FROM clause, as there are several functions and features only available to vertex and edge aliases. +==== diff --git a/modules/querying/pages/select-statement/from-clause-v3.adoc b/modules/querying/pages/select-statement/from-clause-v3.adoc new file mode 100644 index 00000000..8ccda483 --- /dev/null +++ b/modules/querying/pages/select-statement/from-clause-v3.adoc @@ -0,0 +1,203 @@ += FROM Clause (Syntax V3 - GQL Compatible) +:navtitle: From Clause (V2) +:toc: + +[#_from_clause] +The FROM clause in GSQL is used to define path patterns for traversing the graph structure. +It is analogous to the MATCH clause in OpenCypher. + +It has the form + + FROM path_pattern + +A _path_ is a chain of vertices, linked by edges. +A _path pattern_ is a template expression for a path. +Formally, it is a chain of _vertex patterns_, linked by _edge patterns_. +The `FROM` clause searches for all paths that satisfy the path pattern. + +Here is an example of a FROM clause: + + FROM (s:Student) -[e:visited]-> (c:Country) + +`(s:Student)` and `(c:Country)` are vertex patterns. +`-[e:visited]\->` is an edge pattern. + +[NOTE] +==== +GSQL V3 supports the path pattern syntax of GQL as well as the GSQL V2 syntax. +The language parser automatically detects which syntax you are using. +==== + +[#_vertex_and_edge_aliases] +== Pattern Matching and Aliases + +The path pattern in preceding section means find the students who visited at least one country. +When a query is executed, a FROM clause generates a _binding table_. In this example, the columns of the table are `s`, `e`, and `c`, the three _aliases_. Each row of the table is a full set of aliases values that satisfies the pattern. + +For example, if + +[console] +---- + Maria visited Germany + Ahmed visited Japan +---- + +Aliases enable the subsequent parts of the query to refer to the pattern matches. For example `s` is the set (Maria, Ahmed). Likewise `c` is (Germany, Japan) + +However, if a clause refers to multiple aliases, it will maintain the row-wise integrity of the table. +For example, if an expression refers to both `s` and `c`, it will yield (Maria, Germany) and (Ahmed, Japan). +It will not yield (Maria, Japan) pr (Ahmed, Germany). + + +== Vertex Patterns + +A vertex pattern expresses a set of candidate vertices. +The fundamental notation is a pair of parentheses `( )`. +Within the parentheses is an _alias_, following by a colon, following by one or more vertex sets or vertex types, separated by vertical bars. This is optionally followed by a _pattern filter_. + +`(c:company)` + +Strictly speaking, the alias and vertex sets are optional, as shown in the table below. + +.Vertex Pattern Examples +[cols="2,3", separator="!"] +|=== +! Example ! Explanation + +!`(v:Account)` +!All Account vertices, aliased with `v` + +!`(:Account)` +!All Account vertices. No alias, so the matching vertices cannot be referred to later in the query. + +!`(v:)` +!All vertices, aliased with `v` + +!`(v:Account|Post)` +!All Account and Post vertices, aliased with `v` + +!`(v:Post {owner: "Lee"})` +!All Post vertices which satisfy the filter of attribute `owner` be equal to `Lee`, aliased with `v` +|=== + +== Edge Patterns + +An edge pattern expresses a set of candidate edges. +Edge patterns are more complicated than vertex patterns because edges have directionality. +The fundamental notation is a pair of square brackets [ ], which are themselves bracketed by _directionality markers_. + +Within the square brackets, the syntax is analogous to that of vertex patterns: an alias, a set of edge types or edge sets, and an optional filter. + +The table below lists the directionality markers. + +.Edge Directionality +[cols="1,^1", separator="!", none] +|=== +! Orientation ! Example + +! Directed Left +! `\<-[e]-` + +! Directed Right +! `-[e]\->` + +! Directed Left or Right +! `\<-[e]\->` + +! Undirected +! `\~[e]~` + +! Undirected or Directed Left +! `<\~[e]~` + +! Undirected or Directed Right +! `\~[e]~>` + +! Undirect, Directed Left, or Directed Right +! `-[e]-` +|=== + +=== Pattern Quantifiers + +GSQL has a special syntax for a repeated sequence of a pattern (usually repeated edges). +This shorthand is useful when the pattern is focusing only on the relationships (e.g., number of hops) and does not need to refer to the vertices amidst the repeated edges. For example, + + (s:Person{name:"Paul Erdos"}) -[:coauthor]-{1:3} (t:Person) + +means find all the Persons (alias `t`) who are within 3 degrees of coauthor connection with Paul Erdos. + +GSQL V3 supports two notations for edge quantifiers, GQL style and the GSQL style originating in GSQL V2. + +.GQL Style Pattern Quantifiers +[cols="1,2, 2", separator="!", none] +|=== +! Orientation ! Description ! Example + +! `{m,n}` +! from m to n repetitions +! `-[:paid]\->{2,4}` + +! `{m,}` +! m or more repetitions +! `-[:paid]\->{2,}` + +! `{,n}` +! from 0 to n repetitions +! `-[:paid]\->{,4}` + +! `*` +! 0 or more repetitions +! `-[:paid]\->*` + +! `+` +! 1 or more repetitions +! `-[:paid]\->+` +|=== + +.GSQL Style Pattern Quantifiers +[cols="1,2, 2", separator="!", none] +|=== +! Orientation ! Description ! Example + +! `*m..n*` +! from m to n repetitions +! `-[:paid*2..4]\->` + +! `*m..` +! m or more repetitions +! `-[:paid*m..]\->` + +! `*..n` +! 0 to n repetitions +! `-[:paid*..n]\->` + +! `*n` +! exactly n repetitions +! `-[:paid*n]\->*` + +! `*` +! 1 or more times +! `-[:paid*]\->*` +|=== + +=== Conjunctive Pattern Matching + +The pattern we have described so far are all linear path patterns. +You can combine two or more linear path patterns, simply by forming them as a comma-separated list. +They form a conjunction, meaning all of them must be satisfied in order to have a valid match result. + +The aliases used among them are shared. +So, if you use `s` in one pattern and `s` in another pattern, the are the same `s`. +This enables you to combine the linear patterns to for a "V"-shaped or "X"-shaped pattern + +For example: + +[console] +---- +(p:Person{name:"Paul Erdos"}) -[:coauthor]-{1:3} (t:Person), +(k:Person{name:"Kevin Bacon"}) -[:worked_with]-{1:3} (t:Person) +---- + +Find Persons (alias `t`) who both are within 3 coauthorship hops of Paul Erdos and within 3 coworker hops of Kevin Bacon. + + diff --git a/modules/querying/pages/select-statement/index.adoc b/modules/querying/pages/select-statement/index.adoc index 27c4ac19..87a0bc65 100644 --- a/modules/querying/pages/select-statement/index.adoc +++ b/modules/querying/pages/select-statement/index.adoc @@ -34,8 +34,6 @@ gsqlSelectBlock := gsqlSelectClause gsqlSelectClause := vertexSetName "=" SELECT vertexAlias ---- - - The initial clause is the `SELECT` clause: `SELECT vertexAlias`. Its purpose is to specify which set of vertices from the `FROM` clause is to become the output. @@ -49,373 +47,209 @@ The `SELECT` block has many optional clauses, which fit together in a logical fl Overall, the `SELECT` block starts from a source set of vertices and returns a result set that is either a subset of the source vertices or a subset of their neighboring vertices. Along the way, computations can be performed on the selected vertices and edges. - [#_from_clause] -== `FROM` +== FROM Clause (Syntax V3 - GQL Compatible) +:navtitle: From Clause (V2) -The `FROM` clause describes either a single _hop_ or a multi-hop _path pattern_. -Path patterns also have many other options for finer control and greater flexibility. -.`FROM` clause -[source,ebnf] ----- -fromClause := FROM ( pathPattern ["," pathPattern]*) ----- +The FROM clause in GSQL is used to define path patterns for traversing the graph structure. +It is analogous to the MATCH clause in OpenCypher. -A _hop_ or _step_ consists of going from a starting set of vertices, crossing over a set of their edges, to an ending set of vertices. +It has the form + FROM path_pattern -[#_path_pattern] -=== Path pattern -A path pattern specifies sets of vertex types and how they are connected by edge types. +A _path_ is a chain of vertices, linked by edges. +A _path pattern_ is a template expression for a path. +Formally, it is a chain of _vertex patterns_, linked by _edge patterns_. +The `FROM` clause searches for all paths that satisfy the path pattern. -A path pattern starts with a source vertex set, traverses through specified path edge patterns to another step vertex set. -This is called a _hop_. -From the other step vertex set, it can perform multiple hops and traverse to other step vertex sets. +Here is an example of a FROM clause: -Notice that a path pattern can be just a single source vertex set; the subsequent path edge pattern and step vertex sets are optional. + FROM (s:Student) -[e:visited]-> (c:Country) -.EBNF for path pattern -[source,ebnf] ----- -pathPattern := sourceVertexSet ["-" "(" pathEdgePattern ")" "-" stepVertexSet]* ----- +`(s:Student)` and `(c:Country)` are vertex patterns. +`-[e:visited]\->` is an edge pattern. -[#_source_vertex_set] -==== Source vertex set -The source vertex set is the vertex set from which a path pattern starts. -A source vertex set can be denoted by one of the following: - -* `_` or `ANY`, or omitted. -If the source vertex type is omitted, you must give the source vertex set an <<_vertex_and_edge_aliases,alias>>. -* Vertex type -* A vertex set variable +[NOTE] +==== +GSQL V3 supports the path pattern syntax of GQL as well as the xref:select-statement/from-clause-v2.adoc[GSQL V2 syntax]. +The language parser automatically detects which syntax you are using. +==== -Optionally, you can give a source vertex set an alias by appending the alias after a colon``:``. -Although declaring an alias is optional, it is strongly recommended that you declare them. -In the later clauses of the `SELECT` block , you can only refer to vertex sets in the `FROM` clause by their aliases. +[#_vertex_and_edge_aliases] +=== Pattern Matching and Aliases -.EBNF for source vertex set -[,ebnf] ----- -sourceVertexSet := [sourceVertexTypes] [":" vertexAlias] -sourceVertexTypes := "_" | ANY | "(" sourceVertexSetType ["|" sourceVertexSetType]* ")" -sourceVertexSetType := vertexType | vertexSetVariableName ----- +The path pattern in preceding section means find the students who visited at least one country. +When a query is executed, a FROM clause generates a _binding table_. In this example, the columns of the table are `s`, `e`, and `c`, the three _aliases_. Each row of the table is a full set of aliases values that satisfies the pattern. -Belows are a few examples of valid source vertex sets in `SELECT` statements: +For example, if -[tabs] -==== -Vertex type:: -+ --- -[.wrap,gsql] +[console] ---- -Result = SELECT src - FROM Person:src -( - WHERE src.first_name == "Viktor" AND src.last_name == "Akhiezer" - ACCUM CASE - WHEN tgt.type == "Comment" THEN - src.@comment_cnt += 1 - WHEN tgt.type == "Post" THEN - src.@post_cnt += 1 - END; + (Maria) -[visited]-> (Germany) + (Ahmed) -[visited]-> (Japan) ---- -<1> `Person` is a vertex type. -`(Comment | POST)` combines two vertex types. --- -Any type:: -+ --- -You can use `_` or `ANY` to represent any vertex types. -You can also choose to omit the step vertex type altogether to represent any vertex type. -If you choose to omit the type, you must give the step vertex set an alias. -[.wrap,gsql] ----- -Result = SELECT tgt - FROM :s -(>, step vertex sets have more flexibility in how they are denoted. -A step vertex set can be denoted by one of the following: +However, if a clause refers to multiple aliases, it will maintain the row-wise integrity of the table. +For example, if an expression refers to `(s, c)`, it will yield (Maria, Germany) and (Ahmed, Japan). +It will not yield (Maria, Japan) or (Ahmed, Germany). -* `_` or `ANY`, or omitted. -If the step vertex type is omitted, you must give the step vertex set an alias. -* Vertex type -* A vertex set variable -* A global accumulator +=== Vertex Patterns -Optionally, you can give a source vertex set an alias by appending the alias after a colon``:``. -Although declaring an alias is optional, TigerGraph strongly suggests that you declare them. -In the later clauses of the `SELECT` block , you can only refer to vertex sets in the `FROM` clause by their aliases. +A vertex pattern expresses a set of candidate vertices. +The fundamental notation is a pair of parentheses `( )`. +Within the parentheses is an _alias_, following by a colon, following by one or more vertex sets or vertex types, separated by vertical bars. This is optionally followed by a _pattern filter_. +`(c:company)` -.EBNF for step vertex set -[.wrap,ebnf] ----- -stepVertexSet := [stepVertexTypes] [":" vertexAlias] -stepVertexTypes := atomicVertexType | "(" vertexSetType ["|" vertexSetType]* ")" -atomicVertexType := "_" | ANY | vertexSetType -vertexSetType := vertexType | vertexSetVariableName | globalAccumName ----- +Strictly speaking, the alias and vertex sets are optional, as shown in the table below. -Belows are a few examples of valid step vertex sets in `SELECT` statements: +.Vertex Pattern Examples +[cols="2,3", separator="!"] +|=== +! Example ! Explanation -[tabs] -==== -Vertex type:: -+ --- -[.wrap,gsql] ----- -Result = SELECT tgt - FROM Person:tgt -( - WHERE tgt.firstName == "Viktor" AND tgt.lastName == "Akhiezer" - ACCUM CASE - WHEN src.type == "Comment" THEN - tgt.@commentCnt += 1 - WHEN src.type == "Post" THEN - tgt.@postCnt += 1 - END; ----- -<1> `Person` is a vertex type. -`(Comment | POST)` combines two vertex types. --- -Any type:: -+ --- -You can use `_` or `ANY` to represent any vertex types. -You can also choose to omit the step vertex type altogether to represent any vertex type. -If you choose to omit the type, you must give the step vertex set an alias. +!`(v:Account)` +!All Account vertices, aliased with `v` -[.wrap,gsql] ----- -Result = SELECT s - FROM Person:s -(Likes>)- :tgt - WHERE s.first_name == "Viktor" AND s.last_name == "Akhiezer" ----- --- -Vertex set:: -+ --- -A step vertex set can also be represented by a vertex set variable. -[.wrap,gsql] ----- -include::appendix:example$friend_net/select_statement_index_step_vertex_set.gsql[] ----- --- -Global accumulator:: -+ --- -A step vertex set can be represented by a global accumulator of strings (the strings are vertex types). -The accumulator must be of type `SetAccum`, `BagAccum` or `ListAccum`. +!`(:Account)` +!All Account vertices. No alias, so the matching vertices cannot be referred to later in the query. -[.wrap,gsql] ----- -include::appendix:example$friend_net/select_statement_index_step_vertex_global_accumulator.gsql[] ----- --- -==== +!`(v:)` +!All vertices, aliased with `v` -==== Path edge pattern -The path edge pattern represents the relationship between a source vertex set to a step vertex set or from a step vertex set to the next step vertex set. +!`(v:Account|Post)` +!All Account and Post vertices, aliased with `v` -.EBNF for path edge pattern ----- -pathEdgePattern := atomicEdgePattern - | "(" pathEdgePattern ")" - | pathEdgePattern "." pathEdgePattern - | disjPattern - | starPattern +!`(v:Post {owner: "Lee"})` +!All Post vertices which satisfy the filter of attribute `owner` be equal to `Lee`, aliased with `v` +|=== -atomicEdgePattern := atomicEdgeType - | atomicEdgeType ">" - | "<" atomicEdgeType +=== Edge Patterns -atomicEdgeType := "_" | ANY | edgeSetType +An edge pattern expresses a set of candidate edges. +Edge patterns are more complicated than vertex patterns because edges have directionality. +The fundamental notation is a pair of square brackets [ ], which are themselves bracketed by _directionality markers_. -disjPattern := atomicEdgePattern ("|" atomicEdgePattern)* +Within the square brackets, the syntax is analogous to that of vertex patterns: an alias, a set of edge types or edge sets, and an optional filter. -starPattern := ([atomicEdgePattern] | "(" disjPattern ")") "*" [starBounds] +The table below lists the directionality markers. -starBounds := CONST_INT ".." CONST_INT - | CONST_INT ".." - | ".." CONST_INT - | CONST_INT ----- +.Edge Directionality +[cols="1,^1", separator="!", none] +|=== +! Orientation ! Example -A path edge pattern can represent one hop or repeated hops. -A path edge pattern is denoted by `-()-`, where the relationship between vertex sets is specified between the parentheses. +! Directed Left +! `\<-[e]-` -[discrete] -==== Atomic edge pattern +! Directed Right +! `-[e]\->` -The most basic form for a path edge pattern is an atomic edge pattern. -An atomic edge pattern can be one of the following: +! Directed Left or Right +! `\<-[e]\->` -* `_` or `ANY`. -* An edge type. -* A string parameter. -The value of the parameter must be an edge type and can be provided at runtime. -You do not need to specify a direction when using a string parameter to specify the edge type. -* A global `SetAccum` accumulator of strings. -Each string is the name of an edge type. +! Undirected +! `\~[e]~` -If the edge is directed, an atomic edge pattern has either a left pointer `<` on the left or a right pointer `>` on the right to indicate edge direction. -If the edge is undirected, the atomic edge pattern does not have a pointer. -Suppose we have 3 edge types or parameters called A, B, C. +! Undirected or Directed Left +! `<\~[e]~` -* `A>` is a rightward facing A edge -* `` -For example: +! Undirect, Directed Left, or Directed Right +! `-[e]-` +|=== -* `-(STUDY_AT>)-` refers to forward traversal of the directed edge type `STUDY_AT`. -* `-()-`. -* `-(KNOWS)-` refers to forward traversal of the undirected `KNOWS`. -* `-(_>)-` refers to forward traversal of any directed edge types. -* `-(_)-` refers to forward traversal of any undirected edge types. -* `-(<_)-` refers to backward traversal of any directed edge types. +=== Pattern Quantifiers -[discrete] -==== Disjunction pattern -Pattern disjunction allows a path edge pattern to indicate an `OR` relationship between two or more atomic patterns. -If an edge matches any of the atomic patterns, the edge matches the path edge pattern. +GSQL has a special syntax for a repeated sequence of a pattern (usually repeated edges). +This shorthand is useful when the pattern is focusing only on the relationships (e.g., number of hops) and does not need to refer to the vertices amidst the repeated edges. For example, -.EBNF for disjunction pattern -[,ebnf] ----- -disjPattern := atomicEdgePattern ("|" atomicEdgePattern)* ----- + (s:Person{name:"Paul Erdos"}) -[:coauthor]-{1:3} (t:Person) -For example: +means find all the Persons (alias `t`) who are within 3 degrees of coauthor connection with Paul Erdos. -* `-(KNOWS|STUDY_AT>)-` refers to traversing an undirected `KNOWS` edge or a directed `STUDY_AT` edge. -* `-(KNOWS|_>)-` refers to traversing an undirected `KNOWS` edge or any directed edge from left to right. +GSQL V3 supports two notations for edge quantifiers, GQL style and the GSQL style originating in GSQL V2. +.GQL Style Pattern Quantifiers +[cols="1,2, 2", separator="!", none] +|=== +! Orientation ! Description ! Example -==== Pattern repetition -The Kleene star``*`` and `min..max` range specifiers repeat an edge pattern for a specified number of times. -The range specifiers must be integers and must be constants. -See xref:tutorials:pattern-matching/repeating-a-pattern.adoc[] for a tutorial on how to use pattern repetition in a path edge pattern. +! `{m,n}` +! from m to n repetitions +! `-[:paid]\->{2,4}` -.EBNF for star pattern -[,ebnf] ----- -starPattern := ([atomicEdgePattern] | "(" disjPattern ")") "*" [starBounds] +! `{m,}` +! m or more repetitions +! `-[:paid]\->{2,}` -starBounds := CONST_INT ".." CONST_INT - | CONST_INT ".." - | ".." CONST_INT - | CONST_INT ----- +! `{,n}` +! from 0 to n repetitions +! `-[:paid]\->{,4}` -* Add `*` to the end of a pattern to have the star pattern match all paths where the edge pattern occurs one or more times. -** For example, `Person:s - (Friendship*) - Person` matches all paths between two `Person` vertices connected by any number of `Friendship` edges. -** The vertices in the middle do not need to be `Person` vertices. -For example, a path like `person1 -(Friendship)- dog1 - (Friendship) - person2` matches the star pattern. -* Add `*` to the end of a pattern, and then a number after the star to have the star pattern match paths where the edge pattern occurs for the specified number of times. -** For example, `Person:s - (Friendship*2) - Person` matches all paths between two `Person` vertices connected by exactly two `Friendship` edges. -The vertices in the middle do not need to be `Person` vertices. -* Add `*` to the end of a pattern, and then a range after the star (`*x..y`) to have the star pattern match all paths where the edge pattern occurs as many times as within the specified range. -** For example, `Employee:s - (Works_For>*2..4) - Employee` matches all paths between two `Employee` vertices with 2 - 4 right-directed `Works_For` edges. -The vertices in the middle do not need to be `Person` vertices. +! `*` +! 0 or more repetitions +! `-[:paid]\->*` +! `+` +! 1 or more repetitions +! `-[:paid]\->+` +|=== +.GSQL Style Pattern Quantifiers +[cols="1,2, 2", separator="!", none] +|=== +! Orientation ! Description ! Example -==== Pattern concatenation -The dot operator``.`` means concatenate the two edge patterns into one. -The vertex joining the two edges is omitted from the syntax. -The dot operator is a shorthand, when you don’t care about the type of that intermediate vertex. -`(A>.` -For example, the following `FROM` clauses produce the same source and target vertex sets. -While the second `FROM` clause is more concise, it does not give you access to the intermediate vertex and edge sets. +! `*m..` +! m or more repetitions +! `-[:paid*m..]\->` -[.wrap,gsql] ----- -SELECT x -FROM X:x -(E2>:e2)- Y:y -( +! `*..n` +! 0 to n repetitions +! `-[:paid*..n]\->` +! `*n` +! exactly n repetitions +! `-[:paid*n]\->*` -SELECT u -FROM X:x -(E2>. ----- -<1> This `FROM` clauses uses a longer pattern, but gives you access to `y`, `e2`, `z` and `e4`. -<2> This `FROM` clauses is more concise than the first `FROM` clause, but does not give you access to the intermediate vertex and edge sets. +! `*` +! 1 or more times +! `-[:paid*]\->*` +|=== -==== Conjunctive Pattern Matching +=== Conjunctive Pattern Matching -The optional repeating phrase `["," pathPattern]*` allows you to have multiple path patterns. +The pattern we have described so far are all linear path patterns. +You can combine two or more linear path patterns, simply by forming them as a comma-separated list. They form a conjunction, meaning all of them must be satisfied in order to have a valid match result. -See xref:tutorials:pattern-matching/adv/conjunctive-pattern-matching.adoc[] for more details. -[source,ebnf] ----- -fromClause := FROM (step | stepV2 | pathPattern ["," pathPattern]*) ----- - -Each step pattern or path pattern forms a match table, one row per matching path in the graph. -Each vertex alias or edge alias is one column in the table. -When we have a conjunctive path, each path must share at least one vertex alias with another path. -This enables the two path sets (and match tables) to be joined. -Formally, we make the natural join of the two tables. +The aliases used among them are shared. +So, if you use `s` in one pattern and `s` in another pattern, the are the same `s`. +This enables you to combine the linear patterns to for a "V"-shaped or "X"-shaped pattern +For example: -[#_vertex_and_edge_aliases] -=== Vertex and Edge Aliases - -Vertex and edge _aliases_ are declared within the `FROM` clause of a `SELECT` block, by using the colon `:`, followed by the alias name. -Aliases can be accessed anywhere within the same `SELECT` block. -They are used to reference a single selected vertex or edge of a set. -It is through the vertex or edge aliases that the attributes of these vertices or edges can be accessed. - -For example, the following code snippets show two different `SELECT` statements. -The first `SELECT` statement starts from a vertex set called `allVertices`, and the vertex alias name `v` can access each individual vertex from `allVertices`. -The second `SELECT` statement selects a set of edges.It can use the vertex alias `s` to reference the source vertices, or the alias `t` to reference the target vertices. - -.Vertex variables -[source,gsql] +[console] ---- -results = SELECT v FROM all_vertices:v; -results = SELECT t FROM all_vertices:s -()- :t; +(p:Person{name:"Paul Erdos"}) -[:coauthor]-{1:3} (t:Person), +(k:Person{name:"Kevin Bacon"}) -[:worked_with]-{1:3} (t:Person) ---- -The following example shows an edge-based `SELECT` statement, declaring aliases for all three parts of the edge. -In the `ACCUM` clause, the `e` and `t` aliases are assigned to local vertex and edge variables. +Find Persons (alias `t`) who both are within 3 coauthorship hops of Paul Erdos and within 3 coworker hops of Kevin Bacon. -.Edge variables -[source,gsql] ----- -results = SELECT v - FROM all_vertices:s -(:e)- :t - ACCUM VERTEX v = t, EDGE eg = e; ----- -[WARNING] -==== -We strongly suggest that an alias should be declared with every vertex and edge in the FROM clause, as there are several functions and features only available to vertex and edge aliases. -==== == `SAMPLE` @@ -565,9 +399,9 @@ In the following example, the selection conditions are completely specified in t .`WHERE` used as a filter [source,gsql] ---- -result_set1 = SELECT v FROM S:v-((E1|E2|E3):e)-(V1|V2):t; -result_set2 = SELECT v FROM S:v-(:e)-:t - WHERE t.type IN ("V1", "V2") AND t IN v.neighbors("E1|E2|E3") +result_set1 = SELECT v FROM (v:S) -[e:E1|E2|E3]- (t:V1|V2); +result_set2 = SELECT v FROM (v:S) -[e:]- (t) + WHERE t.type IN ("V1", "V2") AND t IN v.neighbors("E1|E2|E3"); ---- @@ -808,7 +642,7 @@ For example, consider the following clauses: [source,gsql] ---- -FROM Person:A -(Knows.Knows)- Person:C +FROM (A:Person) -[:Knows*2]- (C:Person) WHERE C.email = "Andy@www.com" ACCUM C.@pattern_count += 1 ---- @@ -1286,7 +1120,7 @@ This query does not compile because the having condition is testing the wrong ve CREATE QUERY print_member_about_cats() FOR GRAPH Social_Net { start = {Person.*}; - result = SELECT v FROM start:v -(:e)- Post:tgt + result = SELECT v FROM (v:start) -[e]- (tgt:Post) HAVING tgt.subject == "cats"; PRINT result; } @@ -1377,9 +1211,9 @@ There are three forms: .`LIMIT` scenarios [source.wrap,gsql] ---- -result = SELECT v FROM S -(:e)- :v LIMIT k; <1> -result = SELECT v FROM S -(:e)- :v LIMIT j, k; <2> -result = SELECT v FROM S -(:e)- :v LIMIT k OFFSET j; <3> +result = SELECT v FROM (:S) -[e]- (v) LIMIT k; // <1> +result = SELECT v FROM (:S) -[e]- (v) LIMIT j, k; // <2> +result = SELECT v FROM (:S) -[e]- (v) LIMIT k OFFSET j; // <3> ---- <1> Case 1: k = Count <2> Case 2: j = Offset from the start of the list, k = Count diff --git a/modules/querying/pages/select-statement/select-statement-v1.adoc b/modules/querying/pages/select-statement/select-statement-v1.adoc index 1bf2c281..b48499e4 100644 --- a/modules/querying/pages/select-statement/select-statement-v1.adoc +++ b/modules/querying/pages/select-statement/select-statement-v1.adoc @@ -3,7 +3,7 @@ This page describes the GSQL `SELECT` statement in GSQL Syntax V1. The default syntax is syntax v2. -To use syntax v1, you need to declare the syntax at the query level or in a xref:tigergraph-server:gsql-shell:gsql-sessions.adoc#_session_parameters[session parameter]. +To use syntax v1, you need to declare the syntax at the query level or in a xref:{page-component-version}@tigergraph-server:gsql-shell:gsql-sessions.adoc#_session_parameters[session parameter]. The `SELECT` block uses a _step_ _pattern_ to select some of the graph's vertices and edges. There are a number of optional clauses that define and/or refine the selection by constraining the vertex or edge set or the result set. The final output of a query is either a vertex set known as the _result set_ or a table. @@ -51,7 +51,9 @@ NOTE: As of 3.9.3, GSQL supports openCypher patterns as an alternative to writin .FROM clause [source,ebnf] ---- -fromClause := FROM (step | stepV2 | pathPattern ["," pathPattern]*) +fromClauseV1 := FROM step +fromClauseV2 := FROM stepV2 | pathPattern ["," pathPattern]*) +fromClause := fromClauseV1 | fromClauseV2 ---- A hop or step consists of going from a starting set of vertices, crossing over a set of their edges, to an ending set of vertices. diff --git a/modules/querying/pages/syntax-versions.adoc b/modules/querying/pages/syntax-versions.adoc index 6a534ed0..c0d159a1 100644 --- a/modules/querying/pages/syntax-versions.adoc +++ b/modules/querying/pages/syntax-versions.adoc @@ -1,4 +1,4 @@ -= Query Language Syntax Versions += GSQL Syntax Versions :description: Summary of the differences between GSQL syntax V1 and V2. GSQL has three syntax versions: V3, V2, and V1 (legacy version). diff --git a/modules/querying/pages/write-output-to-cloud.adoc b/modules/querying/pages/write-output-to-cloud.adoc new file mode 100644 index 00000000..9beba4da --- /dev/null +++ b/modules/querying/pages/write-output-to-cloud.adoc @@ -0,0 +1,125 @@ += Writing Output to Cloud Storage +:description: How to configure TigerGraph to write query results to AWS S3 or S3-compatible storage like Ceph, MinIO, or Wasabi +:page-aliases: write-query-data-to-cloud.adoc + +This guide shows you how to configure TigerGraph to write query results to AWS S3 or S3-compatible storage systems, such as Ceph, MinIO, or Wasabi. + +To write to an S3 bucket, you need: + +* Access Key ID +* Secret Access Key +* Endpoint URL for S3-compatible systems + +*Configure the S3 Connection* + +You can configure S3 access in three ways: + +* Cluster-wide using gadmin +* Per-session using GSQL parameters +* Via RESTPP headers + +Choose the method based on whether you want settings to apply to all users or just your session. + +== Use gadmin Config (Cluster-Wide) + +Set S3 credentials for the entire TigerGraph cluster. + +. Open your terminal. +. Run these commands: ++ +[source,bash] +---- +gadmin config set GPE.QueryOutputS3AWSAccessKeyID +gadmin config set GPE.QueryOutputS3AWSSecretAccessKey +gadmin config apply -y +gadmin restart gpe -y +---- +. Replace `` and `` with your S3 credentials. + +[NOTE] +==== +gadmin supports only Access Key ID and Secret Access Key. + +For S3-compatible systems like Ceph, set the endpoint URL using GSQL session parameters or RESTPP headers, as gadmin doesn’t support it. +==== + +== Use GSQL Session Parameters + +Set credentials and the endpoint URL for your current GSQL session. This method suits users working with their own buckets or testing different S3-compatible systems. + +. Open the GSQL shell. +. Run these commands: ++ +[source,gsql] +---- +SET s3_aws_access_key_id = "" +SET s3_aws_secret_access_key = "" +SET s3_endpoint = "http://" +---- +. Replace the placeholders: +* ``: Your S3 access key. +* ``: Your S3 secret key. +* ``: Your S3-compatible server URL, including `http://` or `https://` (for example, `http://192.168.99.1:8080` for Ceph). + +[NOTE] +==== +* These settings apply only to your session. +* Session parameters override gadmin settings. +* For S3-compatible systems, you must set `s3_endpoint` [v4.2.1]. +==== + +== Use RESTPP Headers (API Calls) + +Set S3 parameters in HTTP headers for queries run via RESTPP, such as with curl. This method does not require setting parameters in a GSQL session and is ideal for API integrations or one-off queries. + +. Open your terminal. +. Run a curl command: ++ +[source,bash] +---- +curl -X GET \ + -H "GSQL-S3AWSAccessKeyId: " \ + -H "GSQL-S3AWSSecretAccessKey: " \ + -H "GSQL-S3Endpoint: http://" \ + 'http://:14240/restpp/query//?param=' +---- +. Replace the placeholders: +* ``: Your S3 access key. +* ``: Your S3 secret key. +* ``: Your S3-compatible server URL, including `http://` or `https://`. +* ``: Your TigerGraph server address (for example, `10.244.106.233`). +* ``: Your graph name. +* ``: Your query name. +* ``: The S3 path. + +== Unique File Paths to Avoid Conflicts + +Since S3 is a shared storage system, multiple nodes in a cluster can upload to the same S3 bucket. To avoid naming conflicts (multiple nodes trying to write to the same file), the S3 path will include a prefix based on the instance name: + +* Instance Name: A prefix like GPE_{PartitionId}_{ReplicaId} ensures uniqueness by identifying the instance that generated the output. +* Role: For distributed queries, additional suffixes will be used to differentiate between the manager and worker roles on the same GPE: +** Coordinator: The node managing the query (written as .coordinator). +** Worker: The node processing the query (written as .worker). + +So, your S3 file paths might look like: + +* GPE_{PartitionId}_{ReplicaId}.coordinator +* GPE_{PartitionId}_{ReplicaId}.worker + +== Example + +Consider a scenario where a 3 x 2 cluster is executing a distributed query, and the results are being saved to a file called queryResults. + +In this case, the cluster has 3 partitions, each with 2 replicas, and the query is distributed across multiple nodes. + +The output files generated by the query would be named as follows: + +GPE_0_0.worker.queryResults.csv – This file represents the output from the worker node in partition 0, replica 0. +GPE_0_1.coordinator.queryResults.csv – This file represents the output from the coordinator node in partition 0, replica 1. + +These unique file names help ensure that no conflicts occur when multiple nodes are writing query outputs at the same time. + +== Troubleshoot Common Issues + +* *“Cannot determine target” error*: You didn’t set `s3_endpoint` for an S3-compatible system. Add it in session parameters or RESTPP headers. +* *Connection fails on Ceph, MinIO, or Wasabi*: Verify the endpoint URL includes `http://` or `https://`. Check your bucket permissions and credentials. diff --git a/modules/querying/pages/write-query-data-to-cloud.adoc b/modules/querying/pages/write-query-data-to-cloud.adoc deleted file mode 100644 index c6486d19..00000000 --- a/modules/querying/pages/write-query-data-to-cloud.adoc +++ /dev/null @@ -1,58 +0,0 @@ -= Write Query Output to Cloud - -Before you can write query results to an S3 bucket, you need to set up the connection to the S3 service. This requires credentials like an AWS Access Key ID and Secret Access Key. Make sure the necessary read/write permissions are granted for the S3 bucket. -There are two methods to configure these credentials: - -== Using gadmin config - -This method configures the S3 connection for the entire TigerGraph cluster. Once you set the credentials, they apply to all users in the cluster. Here's how to do it: - -[source,GSQL] ----- -gadmin config set GPE.QueryOutputS3AWSAccessKeyID -gadmin config set GPE.QueryOutputS3AWSSecretAccessKey -gadmin config apply -y -gadmin restart gpe -y ----- -* Replace and with your actual AWS credentials - -== Using GSQL Session Parameters - -This method configures the credentials only for the current session and user. - -[source,GSQL] ----- -SET s3_aws_access_key_id = -SET s3_aws_secret_access_key = ----- -* These parameters are set per session, so each user will need to provide their own credentials if they’re working with S3. -* All queries run during this session will use these credentials to write to S3. - -[NOTE]:If both methods (using gadmin config and GSQL session parameters) are applied simultaneously, the GSQL session parameters take precedence. - -== Unique File Paths to Avoid Conflicts - -Since S3 is a shared storage system, multiple nodes in a cluster can upload to the same S3 bucket.To avoid naming conflicts (multiple nodes trying to write to the same file),the S3 path will include a prefix based on the instance name : - -* Instance Name: A prefix like GPE_{PartitionId}_{ReplicaId} ensures uniqueness by identifying the instance that generated the output. -* Role: For distributed queries, additional suffixes will be used to differentiate between the manager and worker roles on the same GPE: -** Coordinator: The node managing the query (written as .coordinator). -** Worker: The node processing the query (written as .worker). - -So, your S3 file paths might look like: - -* GPE_{PartitionId}_{ReplicaId}.coordinator -* GPE_{PartitionId}_{ReplicaId}.worker - -== Example: - -Consider a scenario where a 3 x 2 cluster is executing a distributed query, and the results are being saved to a file called queryResults. - -In this case, the cluster has 3 partitions, each with 2 replicas, and the query is distributed across multiple nodes. - -The output files generated by the query would be named as follows: - -GPE_0_0.worker.queryResults.csv – This file represents the output from the worker node in partition 0, replica 0. -GPE_0_1.coordinator.queryResults.csv – This file represents the output from the coordinator node in partition 0, replica 1. - -These unique file names help ensure that no conflicts occur when multiple nodes are writing query outputs at the same time. diff --git a/modules/tutorials/images/Components-Edges.png b/modules/tutorials/images/Components-Edges.png new file mode 100644 index 00000000..c6e0bce9 Binary files /dev/null and b/modules/tutorials/images/Components-Edges.png differ diff --git a/modules/tutorials/images/Directed Edge.png b/modules/tutorials/images/Directed Edge.png new file mode 100644 index 00000000..c4074703 Binary files /dev/null and b/modules/tutorials/images/Directed Edge.png differ diff --git a/modules/tutorials/images/Event-Centered Schema.png b/modules/tutorials/images/Event-Centered Schema.png new file mode 100644 index 00000000..a0604aed Binary files /dev/null and b/modules/tutorials/images/Event-Centered Schema.png differ diff --git a/modules/tutorials/images/Granularity - Multiple Edge Types.png b/modules/tutorials/images/Granularity - Multiple Edge Types.png new file mode 100644 index 00000000..bb059f6a Binary files /dev/null and b/modules/tutorials/images/Granularity - Multiple Edge Types.png differ diff --git a/modules/tutorials/images/Granularity - Single Edge Type.png b/modules/tutorials/images/Granularity - Single Edge Type.png new file mode 100644 index 00000000..cb709d6c Binary files /dev/null and b/modules/tutorials/images/Granularity - Single Edge Type.png differ diff --git a/modules/tutorials/images/Modeling Time Hierarchically.png b/modules/tutorials/images/Modeling Time Hierarchically.png new file mode 100644 index 00000000..4b778f8d Binary files /dev/null and b/modules/tutorials/images/Modeling Time Hierarchically.png differ diff --git a/modules/tutorials/images/Multiple relationship between two vertices.png b/modules/tutorials/images/Multiple relationship between two vertices.png new file mode 100644 index 00000000..2a903e83 Binary files /dev/null and b/modules/tutorials/images/Multiple relationship between two vertices.png differ diff --git a/modules/tutorials/images/Reversed Edge.png b/modules/tutorials/images/Reversed Edge.png new file mode 100644 index 00000000..47f348a4 Binary files /dev/null and b/modules/tutorials/images/Reversed Edge.png differ diff --git a/modules/tutorials/images/Undirected edges.png b/modules/tutorials/images/Undirected edges.png new file mode 100644 index 00000000..666aa1e8 Binary files /dev/null and b/modules/tutorials/images/Undirected edges.png differ diff --git a/modules/tutorials/images/User-Centered Schema.png b/modules/tutorials/images/User-Centered Schema.png new file mode 100644 index 00000000..39c607a9 Binary files /dev/null and b/modules/tutorials/images/User-Centered Schema.png differ diff --git a/modules/tutorials/images/Vertex Indexes.png b/modules/tutorials/images/Vertex Indexes.png new file mode 100644 index 00000000..c6c9447f Binary files /dev/null and b/modules/tutorials/images/Vertex Indexes.png differ diff --git a/modules/tutorials/images/accumulator-examples.png b/modules/tutorials/images/accumulator-examples.png new file mode 100644 index 00000000..38670cdf Binary files /dev/null and b/modules/tutorials/images/accumulator-examples.png differ diff --git a/modules/tutorials/images/friendship-social-graph.png b/modules/tutorials/images/friendship-social-graph.png index 00b05d31..fabdd49d 100644 Binary files a/modules/tutorials/images/friendship-social-graph.png and b/modules/tutorials/images/friendship-social-graph.png differ diff --git a/modules/tutorials/images/global-vertex-accumulators-query.png b/modules/tutorials/images/global-vertex-accumulators-query.png new file mode 100644 index 00000000..fc5d9f40 Binary files /dev/null and b/modules/tutorials/images/global-vertex-accumulators-query.png differ diff --git a/modules/tutorials/images/query-output-neighbors.png b/modules/tutorials/images/query-output-neighbors.png new file mode 100644 index 00000000..1849726e Binary files /dev/null and b/modules/tutorials/images/query-output-neighbors.png differ diff --git a/modules/tutorials/nav.adoc b/modules/tutorials/nav.adoc index 3aea2965..24f9e89f 100644 --- a/modules/tutorials/nav.adoc +++ b/modules/tutorials/nav.adoc @@ -1,3 +1,7 @@ -* xref:index.adoc[GSQL Tutorials] -** link:https://github.com/tigergraph/ecosys/blob/master/demos/guru_scripts/docker/tutorial/4.x/README.md[GSQL V3 Tutorial] (on GitHub) -** xref:accumulators-tutorial.adoc[] \ No newline at end of file +* xref:index.adoc[Query Language Tutorials] +** xref:intro:set-gsql-apart.adoc[] +** link:https://github.com/tigergraph/ecosys/blob/master/tutorials/GSQL.md[GSQL V3 Tutorial] (on GitHub) +** link:https://github.com/tigergraph/ecosys/blob/master/tutorials/Cypher.md[TigerGraph OpenCypher] (on GitHub) +** link:https://github.com/tigergraph/ecosys/blob/master/tutorials/VectorSearch.md[Hybrid Vector Search] (on GithHub) +** xref:accumulators-tutorial.adoc[] +** xref:schema-design-guide.adoc[] diff --git a/modules/tutorials/pages/accumulators-tutorial.adoc b/modules/tutorials/pages/accumulators-tutorial.adoc index 3ff67e44..9b7dbc50 100644 --- a/modules/tutorials/pages/accumulators-tutorial.adoc +++ b/modules/tutorials/pages/accumulators-tutorial.adoc @@ -9,7 +9,7 @@ This short tutorial aims to shorten the learning curve of accumulators. In theor == *What is an Accumulator?* .The left box is a GSQL query with different accumulators being accumulated to. The right box shows the accumulator variables' final results. -image::https://lh3.googleusercontent.com/TZfcbUMlXsHvCYVO_ex9QqjlK823ybyrX7aQhv38j35fghJVpsJEtdFBjcjMj1x2pHfHbNUraTgbySriMRttCuNv359iOwnRHDVcRgPyAj9tQLappYXe6ManjmRS27eunYMc2rjG[Screenshots of the console showing accumulators and their results.] +image::accumulator-examples.png[Screenshots of the console showing accumulators and their results.] An accumulator is a state variable in GSQL. Its state is mutable throughout the life cycle of a query. It has an initial value, and users can keep accumulating (using its "+=" built-in operator) new values into it. Each accumulator variable has a type. The type decides what semantics the declared accumulator will use to interpret the "+=" operation. @@ -34,13 +34,13 @@ They can only be updated when their owning vertex is accessible. To differentiat * *@* is used for declaring local accumulator variables. It must be used with a vertex alias in a query block. E.g. `v.@cnt += 1,` where v is a vertex alias specified in a FROM clause of a SELECT-FROM-WHERE query block. .A Social graph with 7 Person vertices and 7 Friendship edges connecting them. -image::https://lh6.googleusercontent.com/zBXxBe-6iSKX2RJZ9ITyC1wLf-gcbuJbzHlqnGCFV6uwjkYHrTYXtW56HzAn2uA-YYw4TQNt2-MFe-nbGXDnNml0K1sRYVdAKlc3SxMYZ5UsRnlWTb4R-fHIcXJillIGsyffAO2H[] +image::friendship-social-graph.png[] Consider a toy social graph modeled by a person vertex type and a person-to-person friendship edge type shown in Figure 2. Below we write a query, which accepts a person, and does a 1-hop traversal from the input person to its neighbors. We use the @@global_edge_cnt accumulator to accumulate the total number of edges we traverse. And we use @vertex_cnt to write to the input person's each friend vertex an integer 1. -image::https://lh5.googleusercontent.com/6PVg2z_7N7SqnLUeZOP2mdh52KQqB_GCZC-x5A6edcAagOWqBKWRPixykP-wS-tnAAqPYBWZbEBQOTHqV1GghvlsObYEW5tLkZ-Nn0lIc0EsAk8_RZRP_-vZQnsNn2Wy-j4sB-e4[] +image::global-vertex-accumulators-query.png[] -image::https://lh4.googleusercontent.com/P8rs2ukMPxoFJKk1x74FNkEa38PTg-KNcC9uJ_BN4ZRcYh5nhDTcjYD4_ajvgBe047-hLRaUbHfMXdEnn2nLzFQXGkRHRBbVb4lY399yZ_7If25HKtCAO0Hymn35Zm5fxdux_YtV[Figure 3. The top box shows a query that given a person, accumulate the edge count into @@global_edge_cnt. The bottom box shows that for each friend of the input person, we accumulate 1 into its @vertex_cnt. ] +image::query-output-neighbors.png[Figure 3. The top box shows a query that given a person, accumulate the edge count into @@global_edge_cnt. The bottom box shows that for each friend of the input person, we accumulate 1 into its @vertex_cnt. ] As Figure 2 shows, Dan has 4 direct friends -- Tom, Kevin, Jenny, and Nancy, each of which holds a local accumulator @vertex_cnt. And the @@global_edge_cnt has value 4, reflecting the fact that for each edge, we have accumulated 1 into it. diff --git a/modules/tutorials/pages/gsql-101/built-in-select-queries.adoc b/modules/tutorials/pages/gsql-101/built-in-select-queries.adoc index ce12d950..536e8fa8 100644 --- a/modules/tutorials/pages/gsql-101/built-in-select-queries.adoc +++ b/modules/tutorials/pages/gsql-101/built-in-select-queries.adoc @@ -183,4 +183,4 @@ curl -X GET "http://localhost:14240/restpp/graph/Social/edges/Person/Tom/Friends } ---- -For more built-in REST endpoints, visit the xref:tigergraph-server:API:built-in-endpoints.adoc[Built-in Endpoints page]. +For more built-in REST endpoints, visit the xref:{page-component-version}@tigergraph-server:API:built-in-endpoints.adoc[Built-in Endpoints page]. diff --git a/modules/tutorials/pages/gsql-101/load-data-gsql-101.adoc b/modules/tutorials/pages/gsql-101/load-data-gsql-101.adoc index 3728c59c..e78e61b8 100644 --- a/modules/tutorials/pages/gsql-101/load-data-gsql-101.adoc +++ b/modules/tutorials/pages/gsql-101/load-data-gsql-101.adoc @@ -13,7 +13,7 @@ If they are elsewhere, then in the loading job script below replace `/home/tiger Enter the following set of commands in the GSQL shell. [NOTE] -In the default Docker installation described in xref:tigergraph-server:getting-started:docker.adoc[], these files are in the folder `/home/tigergraph/tutorial/3.x/gsql101/` +In the default Docker installation described in xref:{page-component-version}@tigergraph-server:getting-started:docker.adoc[], these files are in the folder `/home/tigergraph/tutorial/3.x/gsql101/` .GSQL commands to define a loading job diff --git a/modules/tutorials/pages/index.adoc b/modules/tutorials/pages/index.adoc index 984f8c4d..7cce369d 100644 --- a/modules/tutorials/pages/index.adoc +++ b/modules/tutorials/pages/index.adoc @@ -1,13 +1,23 @@ -= GSQL Tutorials += Query Languages :description: A list of available GSQL tutorials The GSQL (R) Graph Database Language is more than just a query language. It also serves as a DDL (Database Definition Language). -There tutorials will help you get starting learning and using GSQL. +The following tutorials and guides will help you learn, write, and optimize queries, as well as adopt best practices when designing graph schemas and working with advanced features like vector search. +* xref:intro:set-gsql-apart.adoc[] + * link:https://github.com/tigergraph/ecosys/blob/master/demos/guru_scripts/docker/tutorial/4.x/README.md[GSQL Tutorial using V3 syntax (on GitHub)] * xref:accumulators-tutorial.adoc[] +* xref:schema-design-guide.adoc[] + +* link:https://github.com/tigergraph/ecosys/blob/master/tutorials/Cypher.md[TigerGraph OpenCypher (on GitHub)] + +* link:https://github.com/tigergraph/ecosys/blob/master/tutorials/VectorSearch.md[Hybrid Vector Search (on GithHub)] + + + diff --git a/modules/tutorials/pages/pattern-matching/prepare-environment.adoc b/modules/tutorials/pages/pattern-matching/prepare-environment.adoc index 8493c94d..1956265b 100644 --- a/modules/tutorials/pages/pattern-matching/prepare-environment.adoc +++ b/modules/tutorials/pages/pattern-matching/prepare-environment.adoc @@ -25,7 +25,7 @@ For example, Person connects to Tag by the hasInterest edge. Forum connects to P == Prerequisites * A running TigerGraph instance. -See xref:tigergraph-server:getting-started:docker.adoc[] to quickly provision a container running the latest version of TigerGraph. +See xref:{page-component-version}@tigergraph-server:getting-started:docker.adoc[] to quickly provision a container running the latest version of TigerGraph. * You have full privileges to create graphs, load data, and drop graphs. It is recommended that you go through this tutorial with the default user `tigergraph`, which has the `superuser` role with all supported privileges. diff --git a/modules/tutorials/pages/schema-design-guide.adoc b/modules/tutorials/pages/schema-design-guide.adoc new file mode 100644 index 00000000..f8df9fd3 --- /dev/null +++ b/modules/tutorials/pages/schema-design-guide.adoc @@ -0,0 +1,272 @@ += Schema Design Guide + +Designing an effective graph schema is essential for building a scalable and efficient graph database. +The primary goal is to model relationships between data entities that optimize both data retrieval and system resource usage. +A well-structured schema ensures high performance both now and as data grows and queries become more complex. + +This guide covers the key principles and best practices for schema design, explaining how to model relationships, handle data properties, and optimize queries. +These best practices will help you make informed decisions for better performance and scalability, whether you're working on a new schema or upgrading an existing one. + +== Components of a TigerGraph Schema + +=== Vertices and Edges + +In graph databases, vertices and edges are the building blocks of your schema. They define the structure of your data and how it is queried. + +==== Vertices + +Vertices represent entities or objects within your graph, such as people, products, companies, or locations. +Think of vertices as nouns, things or concepts that are part of your data model. For example, a "Person" or a "Product" would be modeled as vertices. + +The following schema creates a *Person* and a *Product* vertex: +[source.wrap,gsql] +---- +CREATE VERTEX Person (PRIMARY_ID id INT, name STRING, age INT) +CREATE VERTEX Product (PRIMARY_ID id INT, name STRING, price FLOAT) +---- + +==== Edges + +Edges, on the other hand, represent relationships between entities. +These relationships are the links that connect one vertex to another. For instance, an edge could represent that a Person "purchased" a Product, or that a Person "works_for" a Company. +Edges are often model verbs connecting two nouns (vertices). + +The following schema creates an edge to represent a *purchased* relationship: + +[source.wrap,gsql] +---- +CREATE EDGE Purchased (FROM Person, TO Product, purchase_date DATE) +---- + +The below figure shows how a 'Person' vertex is connected to a 'Product' vertex by a 'purchased' edge, representing a transactional relationship. + +image::Components-Edges.png[] + +[TIP] +==== +* Model things or concepts (like people, products, locations) as vertices. +* Model relationships (like "purchased", "works_for", "friend_of") as edges. +==== + +=== Options for Relationships + +==== Choosing Edge Direction + +When designing your schema, you must decide whether to use *undirected*, *directed*, or *reversed* edges. +Each type of edge serves a specific purpose depending on how you intend to query and traverse the data. + +*Undirected Edges* + +Use *undirected edges* for *bidirectional relationships*. +In a *friendship relationship*, for example, if *Person A* is friends with *Person B*, then *Person B* is also friends with *Person A*. +This means the relationship works in both directions, and we don’t need to specify a direction for it. + +image::Undirected edges.png[] + +The following GSQL DDL statement creates an xref:gsql-ref:ddl-and-loading:defining-a-graph-schema.adoc#_create_edge[undirected edge] for friendship: + +[source.wrap,gsql] +---- +CREATE UNDIRECTED EDGE Is_Friend_Of (FROM Person, TO Person) +---- + +*Directed Edge* + +*Directed edges* are used for *one-way relationships* where the direction of the relationship matters. +For instance, in a *work relationship*, Person A might work for Company B, but Company B does not work for Person A. +This clearly defines that the relationship flows only from Person A to Company B. + +image::Directed Edge.png[] + +The following schema creates a xref:gsql-ref:ddl-and-loading:defining-a-graph-schema.adoc#_create_edge[directed edge] for *work relationship*: + +[source.wrap,gsql] +---- +CREATE DIRECTED EDGE Works_For (FROM Person, TO Company) +---- + +*Reversed Edge* + +A *reversed edge* allows you to traverse a directed edge in the opposite direction of its semantic flow. +For example, in a *parent-child relationship*, we might define the primary edge as *"parent_of"* (Parent → Child). +However, to easily traverse the relationship in the opposite direction (from Child to Parent), we can use a *reversed edge* with a different name, like "child_of" (Child → Parent). This makes it easy to query in either direction. + +image::Reversed Edge.png[] + +TigerGraph has built-in syntax to define a xref:gsql-ref:ddl-and-loading:defining-a-graph-schema.adoc#_with_reverse_edge[reserved edge] that maintains the same attribute values as its primary edge. +The following schema creates a directed edge plus a reserved edge for a *parent-child* relationship: + +[source.wrap,gsql] +---- +CREATE DIRECTED EDGE Parent_Of (FROM Person, TO Person) WITH REVERSE_EDGE = "Child_Of" +---- + +==== Multiple Relationships Between Two Vertices + +For situations where different types of relationships occur between two vertices (e.g., purchases and reviews, or purchases and returns), you can represent each relationship as a discriminated edge. + +The figure below shows a 'Person' vertex connected to a 'Product' vertex by two different edges: 'purchased' and 'returned'. Each edge clearly indicates a different type of interaction. + +image::Multiple relationship between two vertices.png[] + +The following scheme creates discriminated edges to represent different types of *events* (e.g., *purchase and return*): + +[source.wrap,gsql] +---- +CREATE EDGE Purchase_Event (FROM Person, TO Product, purchase_date DATETIME, quantity INT) +CREATE EDGE Return_Event (FROM Person, TO Product, return_date DATETIME, reason STRING) +---- + +=== Indexing - Optimizing Searches + +Efficient querying relies on optimizing how the data is indexed. When you design a graph schema, proper indexing plays a key role in speeding up searches. + +==== Vertex Indexes + +A vertex index is a design pattern where you model frequently grouped or filtered attributes such as color, brand, or type as their own vertex types instead of simple attributes. +This lets you easily search or filter, for example, all products that are red or from a specific brand. + +In the figure below, "Brand", "Color", and "Type" are vertex types connected to products, making filtering and grouping by these properties efficient and flexible. + +image::Vertex Indexes.png[] + +==== Secondary Indexes + +Use xref:gsql-ref:ddl-and-loading:defining-a-graph-schema.adoc#_alter_index[secondary indexes] when the search behavior justifies having an index and either range queries are needed or a vertex index is not appropriate. + +== Optimizing for Your Use Case + +=== Attributes - Property or Vertex Type + +When defining the properties of entities, you must decide whether to model them as attributes or vertices. + +=== Attributes +Attributes are properties that are directly associated with vertices or edges (e.g., product color, transaction date). + +=== Vertices +Model properties as vertices when they are frequently queried or need to be linked to multiple other vertices (e.g., color as a vertex for products). + +=== Granularity of Edge Types + +When deciding how detailed your relationships should be, you have two options: *multiple edge types* or a *single edge type with attributes*. + +==== Multiple Edge Types + +If your relationship types are well-defined and not to numerous (e.g., "is_friend_of", "is_colleague_of"), use multiple edge types. + +image::Granularity - Multiple Edge Types.png[] + +The following schema creates *multiple edge types* for relationships like friend and colleague: + +[source.wrap,gsql] +---- +CREATE UNDIRECTED EDGE Is_Friend_Of (FROM Person, TO Person) +CREATE UNDIRECTED EDGE Is_Colleague_Of (FROM Person, TO Person) +---- + +==== Single Edge Type with Attributes + +Alternatively, you can use one generic edge type (e.g., "is_related_to") and use an attribute to define the relationship (e.g., "friend", "colleague"). + +image::Granularity - Single Edge Type.png[] + +The following schema uses a *single edge type with an attribute* for relationship type: + +[source.wrap,gsql] +---- +CREATE DIRECTED EDGE Is_Related_To (FROM Person, TO Person, relationship_type STRING) +---- + +[TIP] +==== +* Use multiple edge types for high-specificity relationships. +* Use a single edge type with attributes for *simpler schemas* and better *memory efficiency*. +==== + +=== Modeling Time + +Time is often an essential element in graph schemas, particularly for *event-based queries*. + +==== Modeling Time Hierarchically + +Model time as a hierarchy of vertices, like *Year → Month → Day*, for efficient querying of *time-based* data. + +This structure allows for faster time series querying speed by creating hierarchical datetime structures. The levels and partitioning of each level can be customized to best suit your specific use case. + +This organized time model helps us quickly find things, for example, like finding *all products made in the first 15 days of February 2025*. + +image::Modeling Time Hierarchically.png[] + +The following schema creates the necessary time vertices and their relationships: + +[source.wrap,gsql] +---- +// 1. Define Vertex Types: +CREATE VERTEX Year (PRIMARY_ID year_val INT); +CREATE VERTEX Month (PRIMARY_ID month_val INT, month_name STRING); +CREATE VERTEX Day (PRIMARY_ID day_val INT); +CREATE VERTEX Product (PRIMARY_ID product_id STRING); + +// 2. Define Edge Types to establish hierarchy and relationships: +// Connects a Year to its Months +CREATE DIRECTED EDGE HAS_MONTH (FROM Year, TO Month); + +// Connects a Month to its Days +CREATE DIRECTED EDGE HAS_DAY (FROM Month, TO Day); + +// Connects a Product to a specific Day (where an event related to the product occurred) +CREATE DIRECTED EDGE PRODUCED_ON (FROM Product, TO Day); + +---- + +=== Focal Hub + +A *focal hub* is a *central vertex* that connects to many other vertices via multiple edges. It can become a performance bottleneck in your schema. + +==== Managing Hub Nodes + +If you need to use hub nodes, make sure to optimize them using secondary indexes. + +=== Use Case-Based Schema Design + +Graph schema design should always reflect your use case and query requirements. The type of relationships you need to track will guide your choice of schema design. + +==== Event-Centered Schema + +This design focuses on events as the central element of your application. It’s ideal for use cases where you need to analyze event-driven data. +For example, in an e-commerce platform, events like purchases, returns, or reviews could be central to understanding the relationships between customers and products. + +For example, in an e-commerce schema, *purchases* and *product reviews* would be modeled as key events, with relationships showing how customers interact with products. + +image::Event-Centered Schema.png[] + +==== User-Centered Schema + +This design focuses on user behavior and interactions, making it ideal for applications like social networks or user analytics. +In a user-centered schema, you would model users and their relationships with products, services, or other users. + +For example, in a social network schema, you could model *user interactions* (such as *comments, likes, and shares*) and track user behavior over time. + +image::User-Centered Schema.png[] + +[TIP] +==== +* *Choose an event-centered schema* when your primary focus is on analyzing *events* (like *purchases or transactions*). +* *Choose a user-centered schema* when you want to track *user behavior* and *interactions* across your system. +==== + +=== Recommendation + +Here are some key recommendations for schema design: + +* *Edge Types:* Use multiple edge types when specificity is important; for simpler designs, use a single edge type with attributes. + +* *Attributes vs. Vertices:* Model frequently queried properties as vertices and use attributes for less critical data. + +* *Events:* Model events as vertices when they have properties like timestamps, types, or need to be queried individually. For simple cases, use edge attributes to add event details between two related vertices. + +* *Schema Design:* Choose an event-centered or user-centered schema based on the primary query focus. + +* *Indexing:* Use secondary indexes for range queries and vertex indexes for high-cardinality attributes. + +Following these best practices ensures your TigerGraph schema delivers fast, efficient queries and scales with your data and application needs. diff --git a/modules/vector/nav.adoc b/modules/vector/nav.adoc new file mode 100644 index 00000000..86d22409 --- /dev/null +++ b/modules/vector/nav.adoc @@ -0,0 +1 @@ +* xref:vector:index.adoc[Vector Searches] \ No newline at end of file diff --git a/modules/vector/pages/index.adoc b/modules/vector/pages/index.adoc new file mode 100644 index 00000000..ef6c8523 --- /dev/null +++ b/modules/vector/pages/index.adoc @@ -0,0 +1,333 @@ += Vector Database Operations +:description: TigerGraph's vector database functionality: schema, write, read, index, and similarity search, and hybrid graph+vector search + +The TigerGraph database stores and indexes vectors efficiently, effectively serving as a multi-modal graph + vector database for AI applications. +The storage and indexing are distributed, so vector operations are fast and scalable. + +Each vector is associated with a vertex, serving as a specialty attribute. +The vertex holds the vector's ID and another properties or labels that to be associated with the vector. + +The vector search operations are implemented as functions which can be invoked from within GSQL graph queries. +This enables an extremely rich set of possibilities for hybrid graph+vector queries. + +[NOTE] +==== +This document is intended to be a quick reference to the available functionality. +For a tutorial and examples. see our link:https://github.com/tigergraph/ecosys/blob/master/tutorials/VectorSearch.md[Vector Search tutorial]. +==== + +== Vector Data and Search Specifications + +[%header, cols="2,3"] +|=== + +| Characteristic +| Description + +| Element data type +| FLOAT (32-bit floating point) + +| Max. dimensions (vector length) +| 4096 (Community Edition); 32768 (Enterprise Edition) + +| Similarity metrics +| cosine, L2 (Euclidean) IP (inner product) + +| Approximate search algorithms +| HNSW + +| Indexing +| Automatic, incremental + +| Vector operations +| Load, Read, Exact Similarity Search, Approximate Similarity Search, Top-K Search, Hybrid Graph+Vector Search +|=== + + +== Vector Operations Cheatsheet + +For more details, click on the task links. + +[%header, cols="1,3"] +|=== + +| Task +| Command Cheatsheet + +| xref:#create_vector_schema[Add vectors to schema] +a| In schema change job: + +`ALTER VERTEX vertex_name ADD VECTOR ATTRIBUTE vec_name(vertex_params);` + + +| xref:#loading_vectors[Load vectors] +a| Clause in loading job: +``` +LOAD file_object TO VECTOR ATTRIBUTE vec_name ON VERTEX vertex_name +VALUES (id_col, SPLIT(vec_col, elem_sep)) USING SEPARATOR = field_sep; +``` + +| xref:#vectorSearch[Search for similar vertices] +a| Function call in ACCUM clause returns a vertex set: +`vectorSearch(vectorAttributes, queryVector, k, optionalParam)` + +| xref:#print_vectors[Output vectors] +a| In GSQL query: `PRINT v WITH VECTOR;` + +| xref:#update_vectors[Update vectors] +a| REST: Upsert API + +GSQL: assignment in ACCUM clause + +|=== + +There are several xref:#other_vector_functions[other functions] available for working with vector data. + + +[#create_vector_schema] +== Creating a Vector Schema + +A vector attribute is always added to an existing vertex type, using the `ALTER VERTEX` statement with a `SCHEMA_CHANGE` job. +The `ADD VECTOR ATTRIBUTE` clause adds a vector, and `DROP VECTOR ATTRIBUTE` removed the attribute. + +[source,sql] +.Vector schema syntax +---- +ALTER VERTEX vertex_name ADD VECTOR ATTRIBUTE vec_name(vertex_params); + +where vertex_params = + DIMENSION=dim, + METRIC=metr + [, INDEXTYPE=i_type] + [, DATATYPE=d_type] + +ALTER VERTEX vertex_name DROP VECTOR ATTRIBUTE vec_name; +---- + +[%header, cols="1,2,2"] +|=== + +| Vector parameter* | Decription | Values + +| DIMENSION +| dimensions (length) of vector +| `INT` from 1 to 4096 + +| METRIC +| metric used for measuring similarity. +a| `STRING`: `"COSINE"`, + +`"L2"` (Manhattan), + +`"IP"` (inner product) + +| INDEXTYPE +| Similarity indexing scheme +| `STRING`: `"HNSW"` (default) + +| DATATYPE +| element data type +| `STRING`: `"FLOAT"` (default) + +|=== + +NOTE: Vector parameter names are case-insensitive. + +Example: +[source,gsql] +---- +CREATE GLOBAL SCHEMA_CHANGE JOB add_emb2 { + ALTER VERTEX Account ADD VECTOR ATTRIBUTE emb2(DIMENSION=3, METRIC="L2"); +} +RUN GLOBAL SCHEMA_CHANGE JOB add_emb2 +---- + +[NOTE] +==== +Use the `-N` option when you run a schema change job to modify vector attributes. +For more details, see the xref:ddl-and-loading:modifying-a-graph-schema.adoc#_n[RUN SCHEMA CHANGE] page. +==== + +[#loading_vectors] +== Loading Vectors + +Vectors can be loaded in bulk using GSQL xref:ddl-and-loading:creating-a-loading-job.adoc[loading jobs]. +The can either be loaded to existing vertices or included when new vertices are being created. + +The vector data is presumed to be in some format such as CSV where one separator `field_sep` is used between fields like the vector ID and the vector itself. Another separator `elem_sep` separates the vector's elements from one another. + +[source,GSQL] +.Vector load clause syntax +---- +LOAD file_object TO VECTOR ATTRIBUTE vec_name ON VERTEX vertex_name +VALUES (id_col, SPLIT(vec_col, elem_sep)) USING SEPARATOR = field_sep; +---- + +Example: +[source,gsql] +---- +CREATE LOADING JOB load_s3_file { + + DEFINE FILENAME account; + DEFINE FILENAME accountEmb; + + LOAD account TO VERTEX Account VALUES ($"name", gsql_to_bool(gsql_trim($"isBlocked"))) USING header="true", separator=","; + LOAD accountEmb TO VECTOR ATTRIBUTE em1 ON VERTEX Account VALUES ($0, SPLIT($1, ",")) USING SEPARATOR="|"; +} +---- +`$0` is the first column, holding the vector IDs. +`$1` is the vector, with `"|"` separating them. +The vector itself is subdivided into elements, with `","` as the element separator. +Note the use of the split() to parse the vector. + +* The LOAD VECTOR statement does not support nested built-in token functions. For example: +`SPLIT(gsql_replace(gsql_replace($3,"[",""),"]",""))` will fail to compile. Apply transformations in separate steps before loading. +* When loading vectors through the RESTPP endpoint, if the specified vector attribute does not exist, TigerGraph will not return an error. Double-check attribute names before loading. + +== Search Indexing + +TigerGraph automatically builds an (HNSW) similarity index for the vectors as they are loaded, using the similarity metric that was specified when the vector schema was defined. +The search index is used when the `vectorSearch` function is invoked. + +The index is automatically updated in respond to changes in the vector database. +Because similar calculations take some time, the index can lag behind the data updates. + +If you have many vertex types, index rebuild time increases proportionally, even if the total number of vector records is the same. + +[WARNING] +==== +Vectors which have not yet been indexed will not be included in vector search results. +A database export may not include vectors which have not yet been indexed. +==== + +To check rebuild status: +[source.wrap,bash] +---- +curl -s -X GET "http://:14240/restpp/vector/status" +---- + +* `Rebuild_processing` means the index is still rebuilding. +* `Ready_for_query` means rebuild is complete. + +[#vectorSearch] +== vectorSearch Function + +Once vectors are inserted, the database can be searched for vertices or vectors. +`vectorSearch` is a built-in function for vector (approximate) similarity search. + +[source,GSQL] +.vectorSearch function syntax +---- +result = vectorSearch(vectorAttributes, queryVector, k, optionalParam) +---- +where `result` is a vertex set variable, storing the top-k most similar vertices. + +[%header, cols="1,10"] +|=== + +| Parameter | Description + +| vectorAttributes +| A set of vector attributes to search. Each attribute should be in format `VertexType.VectorName`, e.g., `{Account.eb1, Phone.eb1}` + +| queryVector +| The query (input) vector from which similarity is measured. + +| k +| The number of vectors to return. E.g., if k = 10, `vectorSearch` finds the 10 vectors closest to `queryVector`. + +| optionalParam +a| A map of optional params: + +* vertex candidate set +* EF: the exploration factor in HNSW algorithm +* a global MapAccum storing top-k (vertex, distance score) pairs. + +E.g., `{candidate_set: vset1, ef: 20, distance_map: @@distmap}`. +|=== + +The meaning of the optional parameters is best explained by example. See the link:https://github.com/tigergraph/ecosys/blob/master/tutorials/VectorSearch.md[Vector Search tutorial]. + +There are some limitations when using vectorSearch() in GSQL queries: + +* Nested `ListAccum` types inside `vectorSearch()` (e.g., `ListAccum>`) are not supported. +* Using the `+` operator on a `ListAccum` inside `vectorSearch()` is not supported. +* Using vector attributes directly in a WHERE clause (e.g., `WHERE P.embAttr1.size() == 0`) is generally not supported. However, users can now install queries using the `-single` method to avoid Null Pointer Exceptions (NPEs) when working around this limitation. For other cases, use `ACCUM` or `POST-ACCUM` clauses. + +[#print_vectors] +== Printing Vectors + +Note that the `vectorSearch` function returns the set of vertices that are associated with the selected vectors, rather than the vectors themselves. + +To output the vector values, `PRINT` the vertices and include the `WITH VECTOR` clause. +Due to the large size of vectors, this option is usually used when writing the output directly to a file or object store. + +Here is a simple example of a query with a `WITH VECTOR` clause + +[source,gsql] +---- +CREATE OR REPLACE QUERY q1 (LIST query_vector) SYNTAX v3 { + MapAccum @@distances; + + // Find top-5 similar vectors from Account's vector attribute emb1 + // Store the distance in @@distance + v = vectorSearch({Account.emb1}, query_vector, 5, { distance_map: @@distances}); + + PRINT v WITH VECTOR; //show the embeddings + PRINT @@distances; //show the distance map +} +---- + +For more examples, please see the link:https://github.com/tigergraph/ecosys/blob/master/tutorials/VectorSearch.md[Vector Search tutorial]. + + +[#update_vectors] +== Add and Update Vectors + +=== Upsert API + +The existing xref:{page-component-version}@tigergraph-server:API:upsert-rest.adoc[REST API for updating data] can be used for vectors +The vector attribute is treated like standard vector attributes. +The upsert data for a vertex can include zero or more standard attributes and zero or more standard vector attributes, in the same JSON structure. + +For example: + +[console] +---- +curl -X POST "http://localhost:14240/restpp/graph/financialGraph" -d ' +{ + "vertices": { + "Account": { + "9350352": { + "name": { + "value": "Paul Gray" + }, + "emb1": { + "value": [-0.017733968794345856, -0.01019224338233471, -0.016571875661611557] +} } } } } +---- + +=== Assignment in GSQL + +A vertex attribute can be updated like other attributes in the `ACCUM` or `POST-ACCUM` clause of a GSQL query. + +This example assigns new vector values in the last clause: + +[source,gsql] +---- +CREATE OR REPLACE QUERY similarToSame (LIST query_vector) SYNTAX v3 { + + // Find top-5 similar vectors from Account's vector attribute emb1 + // Then update those vectors to be exactly the same as the query vector + sim = vectorSearch({Account.emb1}, query_vector, 5); + + same = SELECT s FROM sim:s + POST-ACCUM s.emb1 = query_vector; +} +---- + + +[#other_vector_functions] +== Other Vector Functions + +The Vector Search tutorial has a list of link:https://github.com/tigergraph/ecosys/blob/master/tutorials/VectorSearch.md#vector-built-in-functions[built-in vector functions]. diff --git a/modules/vector/pages/vector-search.adoc b/modules/vector/pages/vector-search.adoc new file mode 100644 index 00000000..9c13df14 --- /dev/null +++ b/modules/vector/pages/vector-search.adoc @@ -0,0 +1,6 @@ += + + + + +A Ve \ No newline at end of file