Vertex Functions
This page lists the vertex functions that are available in the GSQL query language. The functions are divided into three categories.
-
Dot-syntax methods
-
Object-oriented methods that are invoked on a vertex or vertex alias.
-
-
Vertex-level access control (VLAC) vertex alias methods
-
Object-oriented methods available to vertex aliases that are related to vertex tags.
-
-
Other vertex functions
-
Functions that return a vertex or vertex set, or functions that are closely related to certain attributes of
VERTEX
type variables.
-
Dot-syntax methods
This section lists the built-in methods of vertex aliases. Methods can be accessed by the dot (.
) operator. When noted, a method may also be available to statement-level vertex variables, not just SELECT-body aliases.
edgeAttribute()
filter()
Syntax
v.neighbors().filter( condition )
v.neighborAttribute().filter( condition )
v.edgeAttribute().filter( condition )
Description
This function is appended to neighbors()
, neighborAttribute()
, or edgeAttribute()
to filter the output set according to a filter condition. Only elements that satisfy the condition will be returned.
Parameters
Parameter | Description | Data type |
---|---|---|
|
An expression that evaluates to a boolean value |
|
Example
CREATE QUERY filterEx (SET<STRING> pIds, INT yr) FOR GRAPH workNet api("v2") {
SetAccum<vertex<company>> @recentEmplr, @allEmplr;
BagAccum<string> @diffCountry, @allCountry;
Start = {person.*};
L0 = SELECT v
FROM Start:v
WHERE v.id IN pIds
ACCUM
# filter using edge attribute
v.@recentEmplr += v.neighbors("worksFor").filter(worksFor.startYear >= yr),
v.@allEmplr += v.neighbors("worksFor").filter(true),
# vertex alias attribute and neighbor type attribute
v.@diffCountry += v.neighborAttribute("worksFor", "company", "id")
.filter(v.locationId != company.country),
v.@allCountry += v.neighborAttribute("worksFor", "company", "id")
;
PRINT yr, L0[L0.@recentEmplr, L0.@allEmplr, L0.@diffCountry, L0.@allCountry]; // api v2
}
GSQL > RUN QUERY filterEx(["person1","person2"],2016)
{
"error": false,
"message": "",
"version": {
"edition": "developer",
"schema": 0,
"api": "v2"
},
"results": [{
"L0": [
{
"v_id": "person1",
"attributes": {
"L0.@diffCountry": ["company2"],
"L0.@recentEmplr": ["company1"],
"L0.@allCountry": [ "company1", "company2" ],
"L0.@allEmplr": [ "company2", "company1" ]
},
"v_type": "person"
},
{
"v_id": "person2",
"attributes": {
"L0.@diffCountry": ["company1"],
"L0.@recentEmplr": [],
"L0.@allCountry": [ "company1", "company2" ],
"L0.@allEmplr": [ "company2", "company1" ]
},
"v_type": "person"
}
],
"yr": 2016
}]
}
getAttr()
Parameters
Parameter | Description | Data type |
---|---|---|
|
The name of an attribute. This can be a query parameter, constant string, or global string variable. |
Base types: Container types follow the format Type conversion is supported between numerical values and between |
|
The type of the attribute value |
|
neighborAttribute()
Description
From a vertex, traverses edges of a specified type to its neighbors of a specified type, and returns the set of values for a specified attribute.
neighbors()
Description
Returns the out-neighbors or undirected neighbors of the vertex. If edge types are provided, it will only return the neighbors connected by the specified edge types.
outdegree()
Description
Returns the number of outgoing or undirected edges connected to the vertex. If edge types are provided, it will only return the number of edges of the specified types.
[For 3.9.2+] |
Parameters
Parameter | Description | Data type |
---|---|---|
|
Optional. An edge type or a collection of edge types. |
|
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. |
setAttr()
Description
Sets the specified attribute of a vertex to a new value.
Type conversion is not allowed for setAttr()
.
The input variable types must match the types in the attribute or the accumulator equivalent.
For example, suppose you run v.setAttr("emails", @@emails)
.
If v.emails
is type SET<STRING>
, @@emails
must be type SET<STRING>
or SetAccum<STRING>
.
SetAccum<STRING>
does not support declaring a set or list inside setAttr()
.
VLAC vertex alias methods (Deprecated)
Tag-based Vertex-Level Access Control is deprecated as of October 2023. This feature will be completely removed in v4.0. |
This section covers the vertex alias methods used to access and modify tags on vertices,
addTags()
Example:
CREATE QUERY addTagsToPerson() {
Seed = { any };
# person1 ~ person5 will be tagged as public.
vSet = SELECT s
FROM Seed:s
WHERE s.id IN ("person1","person2","person3","person4","person5")
ACCUM s.addTags("public");
# person6 and person7 will be tagged as public and vip.
vSet = SELECT s
FROM Seed:s
WHERE s.id IN ("person6","person7")
ACCUM s.addTags("vip", "public");
# person8 will be tagged as vip
vSet = SELECT s
FROM Seed:s
WHERE s.id == "person8"
ACCUM s.addTags("vip");
}
getTags()
Descriptions
Returns the vertex’s tags as a set. If the vertex has no tags or is untaggable, it returns an empty set.
Example:
//print the tags of each vertices, in 2 different ways.
CREATE QUERY exampleGettags() {
SetAccum<string> @vAcc;
vSet = { any };
vSet = SELECT s
FROM vSet:s
ACCUM s.@vAcc += s.getTags();
PRINT vSet[vSet.@vAcc];
PRINT vSet[vSet.gettags()];
}
Tip:
|
hasTags()
Description
Returns true
if the vertex has every tag provided in the argument list and returns false
if it does not.
Example:
USE GRAPH socialNet
CREATE QUERY findVertexWithTag(STRING tag) {
seed = { ANY };
res =
SELECT v
FROM seed:v
WHERE v.hasTags(tag)
ORDER BY v.id;
PRINT res WITH TAGS;
}
INSTALL QUERY findVertexWithTag
RUN QUERY findVertexWithTag("vip")
The output of the query would be:
{
"error": false,
"message": "",
"version": {
"schema": 2,
"edition": "enterprise",
"api": "v2"
},
"results": [{"res": [
{
"v_id": "person6",
"attributes": {
"gender": "Male",
"id": "person6",
"res.gettags()": [
"vip",
"public"
]
},
"v_type": "person"
},
{
"v_id": "person7",
"attributes": {
"gender": "Male",
"id": "person7",
"res.gettags()": [
"vip",
"public"
]
},
"v_type": "person"
},
{
"v_id": "person8",
"attributes": {
"gender": "Male",
"id": "person8",
"res.gettags()": ["vip"]
},
"v_type": "person"
}
]}]
}
Vertex functions
The functions in this section either have return values of vertex or vertex set type or are closely related to vertex attributes.
getvid()
Description
Returns the internal ID number of a vertex.
The internal ID is not the primary ID which the user assigned when creating the vertex. However, there is a 1-to-1 mapping between the external ID (primary_id
) and internal ID.
The engine can access the internal ID faster than accessing the external ID, so if a query needs unique values for a large number of vertices, but doesn’t care about particular values, getvid()
can be a useful option. For example, in many community detection algorithms, we start by assigning every vertex a unique community ID. Then, as the algorithm progresses, some vertices will join the community of one of their neighbors, giving up their current community ID and copying the IDs of their neighbors.
Example
CREATE QUERY getvid_ex () FOR GRAPH socialNet {
MinAccum<int> @cc_id; //each vertex's tentative component id
Start = {person.*};
# Initialize: Label each vertex with its own internal ID
S = SELECT x FROM Start:x
POST-ACCUM
x.@cc_id = getvid(x);
# Community detection steps omitted
PRINT Start.@cc_id;
}
{
"error": false,
"message": "",
"version": {
"edition": "developer",
"schema": 0,
"api": "v2"
},
"results": [{"Start": [
{
"v_id": "person7",
"attributes": {"Start.@cc_id": 0},
"v_type": "person"
},
{
"v_id": "person5",
"attributes": {"Start.@cc_id": 4194304},
"v_type": "person"
},
{
"v_id": "person1",
"attributes": {"Start.@cc_id": 4194305},
"v_type": "person"
},
{
"v_id": "person4",
"attributes": {"Start.@cc_id": 11534336},
"v_type": "person"
},
{
"v_id": "person2",
"attributes": {"Start.@cc_id": 13631488},
"v_type": "person"
},
{
"v_id": "person3",
"attributes": {"Start.@cc_id": 20971520},
"v_type": "person"
},
{
"v_id": "person8",
"attributes": {"Start.@cc_id": 22020096},
"v_type": "person"
},
{
"v_id": "person6",
"attributes": {"Start.@cc_id": 24117248},
"v_type": "person"
}
]}]
}
selectVertex()
Description
Reads a data file that lists particular vertices of the graph and returns the corresponding vertex set.This function can only be used in a vertex set variable declaration statement as a seed set and the vertices in the data file must already be in the graph.The data file must be organized as a table with one or more columns.One column must be for vertex ID.Optionally, another column is for vertex type.
Parameters
Parameter | Description | Data type |
---|---|---|
|
The absolute file path of the input file to be read. A relative path is not supported. |
|
|
The vertex ID column position. The index for column positions starts at 0. Therefore, to designate the
first column as the ID column, set this parameter to |
If |
|
The vertex type column position or a specific vertex type. |
If Alternatively, a vertex type without double quotes. |
|
The column separator character. |
|
|
Whether this file has a header. |
`BOO |
Example
ID,type
Dan,person
Jenny,person
Amily,person
CREATE QUERY selectVertexEx(STRING filename) FOR GRAPH socialNet {
S1 = {SelectVertex(filename, $"c1", $1, ",", true)};
S2 = {SelectVertex(filename, $0, person, ",", true)};
PRINT S1, S2; # Both sets of inputs product the same result
}
RUN QUERY selectVertex("/home/tigergraph/mydata/selectVertex.csv")
{
"S1": [
{
"attributes": {
"age": 0,
"gender": "female",
"name": "Amily",
"state": "ca"
},
"v_id": "Amily",
"v_type": "person"
},
{
"attributes": {
"age": 1,
"gender": "male",
"name": "Dan",
"state": "ny"
},
"v_id": "Dan",
"v_type": "person"
},
{
"attributes": {
"age": 1,
"gender": "female",
"name": "Jenny",
"state": "tx"
},
"v_id": "Jenny",
"v_type": "person"
}
],
"S2": [
{
"attributes": {
"age": 0,
"gender": "female",
"name": "Amily",
"state": "ca"
},
"v_id": "Amily",
"v_type": "person"
},
{
"attributes": {
"age": 1,
"gender": "male",
"name": "Dan",
"state": "ny"
},
"v_id": "Dan",
"v_type": "person"
},
{
"attributes": {
"age": 1,
"gender": "female",
"name": "Jenny",
"state": "tx"
},
"v_id": "Jenny",
"v_type": "person"
}
]
}
]
to_vertex()
Running
|
Description
Returns a vertex from a string ID and vertex type. If a vertex with the provided ID and type does not exist, the function will throw a run-time error.
Parameters
Parameter | Description | Data type |
---|---|---|
|
The ID of a vertex |
|
|
The type of the vertex |
|
Example
CREATE QUERY to_vertex_test (STRING uid, STRING vtype) FOR GRAPH social {
VERTEX v;
v = to_vertex (uid, vtype); # to_vertex assigned to a vertex variable
PRINT v; # vertex variable -> only vertex id is printed
}
GSQL > RUN QUERY to_vertex_test("Dan", "person")
{
"error": false,
"message": "",
"version": {
"schema": 1,
"edition": "enterprise",
"api": "v2"
},
"results": [{"v": "Dan"}]
}
to_vertex_set()
Description
Returns a vertex set from a set or bag of string IDs and a vertex type. If there are invalid IDs in the set, those IDs will be skipped and the response will contain a warning message. If the vertex type does not exist, the function will throw a run-time error.
Parameters
Parameter | Description | Data type |
---|---|---|
|
A set of vertex IDs |
|
|
The type of the vertices |
|
Example
CREATE QUERY to_vertex_set_test (SET<STRING> uids, STRING vtype) FOR GRAPH social {
S2 = to_vertex_set (uids, vtype); # to_vertex_set assigned to a vertex set variable
PRINT S2; # vertex set variable-> full details printed
}
GSQL > run query to_vertex_set_test(["Dan", "Amily", "Jeff"], "person")
{
"error": false,
"message": "Runtime Warning: 1 ids are invalid person vertex ids.",
"version": {
"schema": 1,
"edition": "enterprise",
"api": "v2"
},
"results": [{"S2": [
{
"v_id": "Amily",
"attributes": {
"gender": "female",
"name": "Amily",
"state": "ca",
"age": 0
},
"v_type": "person"
},
{
"v_id": "Dan",
"attributes": {
"gender": "male",
"name": "Dan",
"state": "ny",
"age": 1
},
"v_type": "person"
}
]}]
}