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()

Syntax

v.edgeAttribute( edgeType, attrName )

Description

From a vertex, traverse edges of a specified type and return the bag of values for a specified edge attribute.

Return type

BagAccum<attrType>

Parameters

Parameter Description Data type

edgeType

The edge type to traverse

STRING

attrName

The attribute whose value to retrieve

STRING

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.

Return type

BagAccum

Parameters

Parameter Description Data type

condition

An expression that evaluates to a boolean value

BOOL

Example

Example query
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
}
Results
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()

Syntax

v.getAttr(attrName, attrType)

Description

Returns the value of a vertex attribute on the vertex.

Return type

attrType

Parameters

Parameter Description Data type

attrName

The name of an attribute. This can be a query parameter, constant string, or global string variable.

Base types: STRING, INT, UINT, DATETIME, DOUBLE, FLOAT, BOOL

Container types follow the format CONTAINER<TYPE>, where CONTAINER can be LIST or SET and TYPE can be INT, DATETIME, DOUBLE, or STRING.

Type conversion is supported between numerical values and between LIST and SET types. For example, a vertex with an attribute of type LIST<INT> can be retrieved as SET<DOUBLE>.

attrType

The type of the attribute value

STRING

neighborAttribute()

Syntax

v.neighborAttribute( edgeType, targetVertexType, attrName )

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.

Return type

BagAccum<attrType>

Parameters

Parameter Description Data type

edgeType

The edge type to traverse

STRING

targetVertexType

The target vertex type to visit

STRING

attrName

An attribute of the target vertex type

STRING

Example

For the following graph:

Diagram of a graph of Person vertices connected to each other with friendship edges. Each vertex is connected to one or two other vertices except for 'Dan', who is connected to three.
# If v is Jenny
v.neighborAttribute("friendship", "person", "state") -> ["ca", "ny", "ca"]

neighbors()

Syntax

v.neighbors([edgeType])

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.

Return type

BagAccum<VERTEX>

Parameters

Parameter Description Data type

edgeType

Optional. An edge type or a collections of edge types.

STRING, SET<STRING>, SetAccum<STRING>, BagAccum<STRING>, ListAccum<STRING>

Example

For the following graph:

Diagram of a graph of Person vertices connected to each other with friendship edges. Each vertex is connected to one or two other vertices except for 'Dan', who is connected to three.
# If v is Jenny
v.neighbors() -> ["Dan", "Amily", "Tom"]

outdegree()

Syntax

v.outdegree([edgeType])

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+] outdegree() is also available for vertex input parameters. In this case, outdegree() can be used in a query-body statement.

Return type

INT

Parameters

Parameter Description Data type

edgeType

Optional. An edge type or a collection of edge types.

STRING, SET<STRING>, SetAccum<STRING>, BagAccum<STRING>, ListAccum<STRING>

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.

Examples

Vertex alias:

result = SELECT v FROM Members.v
    ACCUM @@num_friends += v.outdegree("is_friend");

Query-body level:

CREATE QUERY outdegree_statement(VERTEX v1) {
  PRINT v1.outdegree();
}

setAttr()

Syntax

v.setAttr( attrName, newValue )

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().

Return type

No return value.

Parameters

Parameter Description Data type

attrName

The name of an attribute. This can be a query parameter, constant string, or global string variable.

STRING

newValue

The new value for the attribute

The type of the attribute.

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()

Syntax

v.addTags(STRING tag1,... STRING tagN)

Description

Adds the tags provided in the argument list to the vertex.

Return type

No return value.

Parameters

Parameter Description Data type

tagN

A tag to add to the vertex

STRING

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");
}

differenceTags()

Syntax

v.differenceTags( v2 )

Description

Returns the difference in tags between the vertex and another vertex as a set.

Return type

SET<STRING>

Paramters

Parameter Description Data type

v2

A vertex

VERTEX

Example:

// return the difference set of tags between two vertices
CREATE QUERY exampleDifferencetags() {
  SetAccum<string> @vAcc;
  vSet = { any };
  vSet = SELECT s
         FROM vSet:s -(_)- :t
         WHERE t.type == "person"
         ACCUM s.@vAcc += s.differenceTags(t);
  PRINT vSet[vSet.@vAcc];
}

getTags()

Syntax

v.getTags()

Descriptions

Returns the vertex’s tags as a set. If the vertex has no tags or is untaggable, it returns an empty set.

Return type

SET<STRING>

Parameters

None.

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: getTags() can be used within a PRINT statement:

  • PRINT R [R.getTags()];

  • or PRINT R WITH TAGS which is syntax sugar, except that it won’t print "R.getTags()": [] for non-taggable vertices.

hasTags()

Syntax

hasTags( tag1, tag2, ..., tagN )

Description

Returns true if the vertex has every tag provided in the argument list and returns false if it does not.

Return type

BOOL

Parameters

Parameter Description Data type

tagN

A string.

STRING

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"
    }
  ]}]
}

isTaggable()

Syntax

v.isTaggable()

Description

Returns true if the vertex is taggable.

Return type

BOOL

Parameters

None

Example:

//count the number of taggable vertices in the graph.
CREATE QUERY countIstaggable() for graph poc_graph_tag {
  SumAccum<int> @@count;
  vSet = { any };
  vSet = SELECT s
         FROM vSet:s
         WHERE s.isTaggable()
         ACCUM @@count += 1;
  PRINT @@count;
}

intersectTags()

Syntax

v.intersectTags( v2 )

Description

Returns the common tags between the vertex and another vertex as a set.

Return type

SET<STRING>

Example:

//return the intersect set of tags between two vertices.
CREATE QUERY exampleIntersecttags() {
  SetAccum<string> @vAcc;
  vSet = { any };
  vSet = SELECT s
         FROM vSet:s -(_)- :t
         WHERE t.type == "person"
         ACCUM s.@vAcc += s.intersectTags(t);
  PRINT vSet[vSet.@vAcc];
}

removeAllTags()

Syntax

v.removeAllTags()

Description

Removes all tags from the vertex.

Return type

No return value.

Parameters

None

Example:

//remove all tags from all person vertices.
CREATE QUERY removealltagsFromPerson() {
  vSet = { person.* };
  # remove all tags from all person vertices
  vSet = SELECT s
         FROM vSet:s
         ACCUM s.removeAllTags();
}

removeTags()

Syntax

removeTags( tag1, tag2, ..., tagN )

Description

Removes the tags provided in the argument list from the vertex.

Return type

No return value.

Parameters

Parameter Description Data type

tagN

A string value

STRING

Example

//remove tag “vip” and “public” from all person vertices.
CREATE QUERY removetagsFromPerson() {
  vSet = { person.* };
  # remove tag vip and public from all person vertices
  vSet = SELECT s
         FROM vSet:s
         ACCUM s.removeTags("vip", "public");
}

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()

Syntax

getvid( v )

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.

Return type

UINT

Parameters

Parameter Description Data type

v

A vertex alias.

Vertex alias

Example

  • Query

  • Result

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()

Syntax

selectVertex( filepath, vertexIdColumn, vertexTypeColumn, seperator, header)

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.

Return type

SET<VERTEX>

Parameters

Parameter Description Data type

filePath

The absolute file path of the input file to be read. A relative path is not supported.

STRING

vertexIdColumn

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 $0.

$ num

If header is set to true, $ "column_name" is also acceptable.

vertexTypeColumn

The vertex type column position or a specific vertex type.

$ num

If header is set to true,$ "column_name" is also acceptable.

Alternatively, a vertex type without double quotes.

separator

The column separator character.

STRING

header

Whether this file has a header.

`BOO

Example

selectVertex.csv
ID,type
Dan,person
Jenny,person
Amily,person
Example query
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
}
Results
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 to_vertex() and to_vertex_set() requires real-time conversion of an external ID to a GSQL internal ID, which is a relatively slow process. Therefore,

  • If the user can always know the id before running the query, define the query with VERTEX or SET<VERTEX> parameters instead of STRING or SET<STRING> parameters, and avoid calling to_vertex() or to_vertex_set().

  • Calling to_vertex_set() one time is much faster than calling to_vertex() multiple times. Use to_vertex_set() instead of to_vertex() as much as possible.

Since v4.1.0, to_vertex() may not be used in ACCUM or POST-ACCUM clauses.

==== Example

Example query using to_vertex() in Accum should propmt an error message
CREATE QUERY myTest() {
    ListAccum<VERTEX> @@myVertices;
    vSet = SELECT src from Person:src
      Accum
        @@myVertices += to_vertex("m1","Person")    # such use case should not be allowed anymore
    ;
}

You should receive a similar error message.

Using a vertex function 'to_vertex' or 'to_vertex_set' in ACCUM/POST-ACCUM,
this has been deprecated. Please rewrite your query.

Syntax

to_vertex( id, vertex_type )

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.

Return type

VERTEX

Parameters

Parameter Description Data type

id

The ID of a vertex

STRING

vertex_type

The type of the vertex

STRING

Example

Example query using to_vertex()
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
}
Query result
GSQL > RUN QUERY to_vertex_test("Dan", "person")
{
  "error": false,
  "message": "",
  "version": {
    "schema": 1,
    "edition": "enterprise",
    "api": "v2"
  },
  "results": [{"v": "Dan"}]
}

to_vertex_set()

Since v4.1.0, to_vertex_set() may not be used in ACCUM or POST-ACCUM clauses.

==== Example

Example query using to_vertex_set() in Accum should propmt an error message
CREATE QUERY myTest2(SET<String> myIds) {
    SetAccum<VERTEX> @@myVertices;
    vSet = SELECT src from Person:src
      Accum
        @@myVertices += to_vertex_set(myIds, "Person")    # such use case should not be allowed anymore
    ;
}

You should receive a similar error message.

Using a vertex function 'to_vertex' or 'to_vertex_set' in ACCUM/POST-ACCUM,
this has been deprecated. Please rewrite your query.

Syntax

to_vertex_set( id_set, vertex_type)

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.

Return type

SET<VERTEX>

Parameters

Parameter Description Data type

id_set

A set of vertex IDs

SET<STRING>, BAG<STRING>

vertex_type

The type of the vertices

STRING

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"
    }
  ]}]
}