This page lists the vertex functions that are available in the GSQL query language. The functions are divided into three categories.
Vertex alias methods
Methods available to vertex aliases
Vertex-level access control(VLAC) vertex alias methods
Methods available to vertex aliases that are related to vertex tags.
Vertex functions
Functions that return a vertex or vertex set, or functions that are closely related to certain attributes of VERTEX
type variables.
This section lists the built-in methods of vertex aliases. Methods can be accessed by the dot (.
) operator.
edgeAttribute()
v.edgeAttribute( edgeType, attrName )
From a vertex, traverse edges of a specified type and return the bag of values for a specified edge attribute.
BagAccum<attrType>
filter()
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.
BagAccum
getAttr()
v.getAttr(attrName, attrType)
Returns the value of a vertex attribute on the vertex.
attrType
neighborAttribute()
v.neighborAttribute( edgeType, targetVertexType, attrName )
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.
BagAccum<attrType>
For the following graph:
neighbors()
v.neighbors([edgeType])
Returns the out-neighbors or undirected neighbors of the vertex. If an edge type is provided, it will only return the neighbors connected by the specified edge type.
BagAccum<VERTEX>
For the following graph:
outdegree()
v.outdegree([edgeType])
Returns the number of outgoing or undirected edges connected to the vertex. If an edge type is provided, it will only return the number of edges of the specified type.
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()
v.setAttr( attrName, attrType, newValue )
Sets the specified attribute of a vertex to a new value.
No return value.
This section covers the vertex alias methods used to access and modify tags on vertices,
addTags()
v.addTags(STRING tag1,... STRING tagN)
Adds the tags provided in the argument list to the vertex.
No return value.
differenceTags()
v.differenceTags( v2 )
Returns the difference in tags between the vertex and another vertex as a set.
SET<STRING>
getTags()
v.getTags()
Returns the vertex's tags as a set. If the vertex has no tags or is untaggable, it returns an empty set.
SET<STRING>
None.
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()
hasTags( tag1, tag2, ..., tagN )
Returns true
if the vertex has every tag provided in the argument list and returns false
if it does not.
BOOL
The output of the query would be:
isTaggable()
v.isTaggable()
Returns true if the vertex is taggable.
BOOL
None
intersectTags()
v.intersectTags( v2 )
Returns the common tags between the vertex and another vertex as a set.
SET<STRING>
removeAllTags()
v.removeAllTags()
Removes all tags from the vertex.
No return value.
None
removeTags()
removeTags( tag1, tag2, ..., tagN )
Removes the tags provided in the argument list from the vertex.
No return value.
The functions in this section either have return values of vertex or vertex set type or are closely related to vertex attributes.
getvid()
getvid( id )
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.
STRING
selectVertex()
selectVertex( filepath, vertexIdColumn, vertexTypeColumn, seperator, header)
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.
SET<VERTEX>
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.
to_vertex( id, vertex_type )
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.
VERTEX
to_vertex_set()
to_vertex_set( id_set, vertex_type)
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.
SET<VERTEX>
Parameter
Description
Data type
edgeType
The edge type to traverse
STRING
attrName
The attribute whose value to retrieve
STRING
Parameter
Description
Data type
condition
An expression that evaluates to a boolean value
BOOL
Parameter
Description
Data type
attrName
A vertex attribute
STRING
attrType
The type of the attribute value
STRING
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
Parameter
Description
Data type
edgeType
Optional. An edge type.
STRING
Parameter
Description
Data type
edgeType
Optional. An edge type.
STRING
Parameter
Description
Data type
attrName
The name of an attribute
STRING
attrType
The type of the attribute
STRING
newValue
The new value for the attribute
STRING
Parameter
Description
Data type
tagN
A tag to add to the vertex
STRING
Parameter
Description
Data type
v2
A vertex
VERTEX
Parameter
Description
Data type
tagN
A string.
STRING
Parameter
Description
Data type
tagN
A string value
STRING
Parameter
Description
Data type
id
The primary ID of a vertex
STRING
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
Parameter
Description
Data type
id
The ID of a vertex
STRING
vertex_type
The type of the vertex
STRING
Parameter
Description
Data type
id_set
A set of vertex IDs
SET<STRING>, BAG<STRING>
vertex_type
The type of the vertices
STRING