---
title: "Vertex Functions"
description: "A list of vertex functions in GSQL."
component: "gsql-ref"
version: "4.3"
module: "querying"
html_url: "/gsql-ref/4.3/querying/func/vertex-methods"
canonical_url: "https://www.tigergraph.com/docs/gsql-ref/4.3/querying/func/vertex-methods"
markdown_url: "https://www.tigergraph.com/docs/gsql-ref/4.3/querying/func/vertex-methods.md"
---

[View as HTML](https://www.tigergraph.com/docs/gsql-ref/4.3/querying/func/vertex-methods)

# 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.
* 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

```bash
v.neighbors().filter( condition )
v.neighborAttribute().filter( condition )
v.edgeAttribute().filter( condition )
```

#### Description

This function is appended to [neighbors()](https://www.tigergraph.com/docs/gsql-ref/4.3/querying/func/vertex-methods.md#_neighbors), [neighborAttribute()](https://www.tigergraph.com/docs/gsql-ref/4.3/querying/func/vertex-methods.md#_neighborattribute), or [edgeAttribute()](https://www.tigergraph.com/docs/gsql-ref/4.3/querying/func/vertex-methods.md#_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

```bash
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

```bash
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.](https://www.tigergraph.com/docs/gsql-ref/4.3/querying/_images/image%20(79).png) 

```bash
# 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.](https://www.tigergraph.com/docs/gsql-ref/4.3/querying/_images/image%20(79)%20(1).png) 

```bash
# 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.

> [!NOTE]
> \[For 3.9.2+\] `outdegree()` is also available for vertex input parameters. In this case, outdegree() can be used in a [query-body statement](https://www.tigergraph.com/docs/gsql-ref/4.3/querying/run-manage-queries.md#_statement_types).

#### 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]
> **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

Vertex alias:

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

Query-body level:

```wrap
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. |

## 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.

> [!NOTE]
> We also support `id()` function that works as an alias for `getvid()`

#### Return type

`UINT`

#### Parameters

| Parameter | Description | Data type |
| --- | --- | --- |
| `v` | A vertex alias. | Vertex alias |

#### Example

* Query
* Result

```gsql
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;
}
```

```json
{
    "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

```bash
ID,type
Dan,person
Jenny,person
Amily,person
```

Example query

```gsql
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

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

> [!NOTE]
> 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
> 
> ```gsql
> 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.
> 
> ```text
> 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()

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

### `to_vertex_set()`

> [!NOTE]
> 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
> 
> ```gsql
> 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.
> 
> ```text
> 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

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

### `elementId()`

#### Syntax

`elementId(v)`

#### Description

Returns an internal string id for a vertex or edge.

This internal ID is not the primary ID which the user assigned when creating the vertex. It is guaranteed to remain the same across the same query run, but not across different runs.

> [!NOTE]
> See section on edge functions for more information on `elementId(EDGE)`.

#### Return type

`STRING`

#### Parameters

| Parameter | Description | Data type |
| --- | --- | --- |
| `v` | A vertex | `VERTEX` |

#### Example

```gsql
CREATE QUERY elementId_example () FOR GRAPH socialNet {
  MinAccum<STRING> @@min_id;       //each vertex's tentative string id

  Start = {person.*};
  # Gather a sample element id for demonstration purposes
  S = SELECT x FROM Start:x
      POST-ACCUM
         @@min_id += elementId(x);

  PRINT @@min_id;
}
```

```gsql
GSQL > run query elementId_example()
{
  "version": {
    "edition": "enterprise",
    "api": "v2",
    "schema": 1
  },
  "error": false,
  "message": "",
  "results": [
    {
      "@@min_id": "160256"
    }
  ]
}
```
