---
title: "Vertex Functions"
component: "pytigergraph"
version: "1.6"
module: "core-functions"
html_url: "/pytigergraph/1.6/core-functions/vertex"
canonical_url: "https://www.tigergraph.com/docs/pytigergraph/1.6/core-functions/vertex"
markdown_url: "https://www.tigergraph.com/docs/pytigergraph/1.6/core-functions/vertex.md"
---

[View as HTML](https://www.tigergraph.com/docs/pytigergraph/1.6/core-functions/vertex)

# Vertex Functions

Functions to upsert, retrieve and delete vertices.

All functions in this module are called as methods on a [TigerGraphConnection object](https://www.tigergraph.com/docs/pytigergraph/1.8/core-functions/base.md).

## getVertexTypes()

`getVertexTypes(force: bool = False) → list`

Returns the list of vertex type names of the graph.

#### Parameter:

* `force`: If `True`, forces the retrieval the schema metadata again, otherwise returns a cached copy of vertex type metadata (if they were already fetched previously).

#### Returns:

The list of vertex types defined in the current graph.

## getVertexAttrs()

`getVertexAttrs(vertexType: str) → list`

Returns the names and types of the attributes of the vertex type.

#### Parameter:

* `vertexType`: The name of the vertex type.

#### Returns:

A list of (attribute\_name, attribute\_type) tuples. The format of attribute\_type is one of - "scalar\_type" - "complex\_type(scalar\_type)" - "map\_type(key\_type,value\_type)" and it is a string.

## getVertexType()

`getVertexType(vertexType: str, force: bool = False) → dict`

Returns the details of the specified vertex type.

#### Parameters:

* `vertexType`: The name of the vertex type.
* `force`: If `True`, forces the retrieval the schema metadata again, otherwise returns a cached copy of vertex type details (if they were already fetched previously).

#### Returns:

The metadata of the vertex type.

## getVertexCount()

`getVertexCount(vertexType: Union[str, list] = "*", where: str = "", realtime: bool = False) → Union[int, dict]`

Returns the number of vertices of the specified type.

#### Parameters:

* `vertexType (Union[str, list], optional)`: The name of the vertex type. If `vertexType` \== "\*", then count the instances of all vertex types (`where` cannot be specified in this case). Defaults to "\*".
* `where (str, optional)`: A comma separated list of conditions that are all applied on each vertex's attributes. The conditions are in logical conjunction (i.e. they are "AND'ed" together). Defaults to "".
* `realtime (bool, optional)`: Whether to get the most up-to-date number by force. When there are frequent updates happening, a slightly outdated number (up to 30 seconds delay) might be fetched. Set `realtime=True` to force the system to recount the vertices, which will get a more up-to-date result but will also take more time. This parameter only works with TigerGraph DB 3.6 and above. Defaults to False.

#### Returns:

* A dictionary of <vertex\_type>: <vertex\_count> pairs if `vertexType` is a list or "\*".
* An integer of vertex count if `vertexType` is a single vertex type.

#### Uses:

* If `vertexType` is specified only: count of the instances of the given vertex type(s).
* If `vertexType` and `where` are specified: count of the instances of the given vertex type after being filtered by `where` condition(s).

#### Raises:

`TigerGraphException` when "\*" is specified as vertex type and a `where` condition is provided; or when invalid vertex type name is specified.

#### Endpoints:

* `GET /graph/{graph_name}/vertices`See [List vertices](https://www.tigergraph.com/docs/tigergraph-server/4.3/API/built-in-endpoints.md#_list_vertices)
* `POST /builtins`See [Run built-in functions](https://www.tigergraph.com/docs/tigergraph-server/4.3/API/built-in-endpoints.md#_run_built_in_functions_on_graph)

## upsertVertex()

`upsertVertex(vertexType: str, vertexId: str, attributes: dict = None) → int`

Upserts a vertex.

Data is upserted:

* If vertex is not yet present in graph, it will be created.
* If it's already in the graph, its attributes are updated with the values specified in the request. An optional operator controls how the attributes are updated.

#### Parameters:

* `vertexType`: The name of the vertex type.
* `vertexId`: The primary ID of the vertex to be upserted.
* `attributes`: The attributes of the vertex to be upserted; a dictionary in this format:  
```none  
{<attribute_name>: <attribute_value>|(<attribute_name>, <operator>), …}  
```  
Example:  
```none  
{"name": "Thorin", points: (10, "+"), "bestScore": (67, "max")}  
```

For valid values of `<operator>` see [Operation codes](https://www.tigergraph.com/docs/tigergraph-server/4.3/API/built-in-endpoints.md#_operation_codes).

#### Returns:

A single number of accepted (successfully upserted) vertices (0 or 1).

#### Endpoint:

* `POST /graph/{graph_name}`See [Upsert data to graph](https://www.tigergraph.com/docs/tigergraph-server/4.3/API/built-in-endpoints.md#_upsert_data_to_graph)

## upsertVertices()

`upsertVertices(vertexType: str, vertices: list) → int`

Upserts multiple vertices (of the same type).

See the description of `upsertVertex` for generic information.

#### Parameters:

* `vertexType`: The name of the vertex type.
* `vertices`: A list of tuples in this format:

```json
[
(<vertex_id>, {<attribute_name>: <attribute_value>, …}),
(<vertex_id>, {<attribute_name>: (<attribute_value>, <operator>), …}),
⋮
]
```

\+ Example:

```json
[
(2, {"name": "Balin", "points": (10, "+"), "bestScore": (67, "max")}),
(3, {"name": "Dwalin", "points": (7, "+"), "bestScore": (35, "max")})
]
```

For valid values of `<operator>` see [Operation codes](https://www.tigergraph.com/docs/tigergraph-server/4.3/API/built-in-endpoints.md#_operation_codes).

#### Returns:

A single number of accepted (successfully upserted) vertices (0 or positive integer).

#### Endpoint:

* `POST /graph/{graph_name}`See [Upsert data to graph](https://www.tigergraph.com/docs/tigergraph-server/4.3/API/built-in-endpoints.md#_upsert_data_to_graph)

## upsertVertexDataFrame()

`upsertVertexDataFrame(df: pd.DataFrame, vertexType: str, v_id: bool = None, attributes: dict = None) → int`

Upserts vertices from a Pandas DataFrame.

#### Parameters:

* `df`: The DataFrame to upsert.
* `vertexType`: The type of vertex to upsert data to.
* `v_id`: The field name where the vertex primary id is given. If omitted the dataframe index would be used instead.
* `attributes`: A dictionary in the form of `{target: source}` where source is the column name in the dataframe and target is the attribute name in the graph vertex. When omitted, all columns would be upserted with their current names. In this case column names must match the vertex's attribute names.

#### Returns:

The number of vertices upserted.

## getVertices()

`getVertices(vertexType: str, select: str = "", where: str = "", limit: Union[int, str] = None, sort: str = "", fmt: str = "py", withId: bool = True, withType: bool = False, timeout: int = 0) → Union[dict, str, pd.DataFrame]`

Retrieves vertices of the given vertex type.

**Note**: The primary ID of a vertex instance is NOT an attribute, thus cannot be used in`select`, `where` or `sort` parameters (unless the `WITH primary_id_as_attribute` clause was used when the vertex type was created).  
Use `getVerticesById()` if you need to retrieve vertices by their primary ID.

#### Parameters:

* `vertexType`: The name of the vertex type.
* `select`: Comma separated list of vertex attributes to be retrieved.
* `where`: Comma separated list of conditions that are all applied on each vertex' attributes. The conditions are in logical conjunction (i.e. they are "AND'ed" together).
* `sort`: Comma separated list of attributes the results should be sorted by. Must be used with `limit`.
* `limit`: Maximum number of vertex instances to be returned (after sorting). Must be used with `sort`.
* `fmt`: Format of the results:  
   * "py": Python objects  
   * "json": JSON document  
   * "df": pandas DataFrame
* `withId`: (When the output format is "df") should the vertex ID be included in the dataframe?
* `withType`: (When the output format is "df") should the vertex type be included in the dataframe?
* `timeout`: Time allowed for successful execution (0 = no limit, default).

#### Returns:

The (selected) details of the (matching) vertex instances (sorted, limited) as dictionary, JSON or pandas DataFrame.

#### Endpoint:

* `GET /graph/{graph_name}/vertices/{vertex_type}`See [List vertices](https://www.tigergraph.com/docs/tigergraph-server/4.3/API/built-in-endpoints.md#_list_vertices)

## getVertexDataFrame()

`getVertexDataFrame(vertexType: str, select: str = "", where: str = "", limit: Union[int, str] = None, sort: str = "", timeout: int = 0) → pd.DataFrame`

Retrieves vertices of the given vertex type and returns them as pandas DataFrame.

This is a shortcut to `getVertices(…​, fmt="df", withId=True, withType=False)`.

**Note**: The primary ID of a vertex instance is NOT an attribute, thus cannot be used in`select`, `where` or `sort` parameters (unless the `WITH primary_id_as_attribute` clause was used when the vertex type was created).  
Use `getVerticesById()` if you need to retrieve vertices by their primary ID.

#### Parameters:

* `vertexType`: The name of the vertex type.
* `select`: Comma separated list of vertex attributes to be retrieved.
* `where`: Comma separated list of conditions that are all applied on each vertex' attributes. The conditions are in logical conjunction (i.e. they are "AND'ed" together).
* `sort`: Comma separated list of attributes the results should be sorted by. Must be used with 'limit'.
* `limit`: Maximum number of vertex instances to be returned (after sorting). Must be used with `sort`.
* `timeout`: Time allowed for successful execution (0 = no limit, default).

#### Returns:

The (selected) details of the (matching) vertex instances (sorted, limited) as pandas DataFrame.

## getVertexDataframe()

`getVertexDataframe(vertexType: str, select: str = "", where: str = "", limit: Union[int, str] = None, sort: str = "", timeout: int = 0) → pd.DataFrame`

DEPRECATED

Use `getVertexDataFrame()` instead.

## getVerticesById()

`getVerticesById(vertexType: str, vertexIds: Union[int, str, list], select: str = "", fmt: str = "py", withId: bool = True, withType: bool = False, timeout: int = 0) → Union[list, str, pd.DataFrame]`

Retrieves vertices of the given vertex type, identified by their ID.

#### Parameters:

* `vertexType`: The name of the vertex type.
* `vertexIds`: A single vertex ID or a list of vertex IDs.
* `select`: Comma separated list of vertex attributes to be retrieved.
* `fmt`: Format of the results:  
"py": Python objects (in a list) "json": JSON document "df": pandas DataFrame
* `withId`: (If the output format is "df") should the vertex ID be included in the dataframe?
* `withType`: (If the output format is "df") should the vertex type be included in the dataframe?
* `timeout`: Time allowed for successful execution (0 = no limit, default).

#### Returns:

The (selected) details of the (matching) vertex instances as dictionary, JSON or pandas DataFrame.

#### Endpoint:

* `GET /graph/{graph_name}/vertices/{vertex_type}/{vertex_id}`See [Retrieve a vertex](https://www.tigergraph.com/docs/tigergraph-server/4.3/API/built-in-endpoints.md#_retrieve_a_vertex)

## getVertexDataFrameById()

`getVertexDataFrameById(vertexType: str, vertexIds: Union[int, str, list], select: str = "") → pd.DataFrame`

Retrieves vertices of the given vertex type, identified by their ID.

This is a shortcut to `getVerticesById(…​, fmt="df", withId=True, withType=False)`.

#### Parameters:

* `vertexType`: The name of the vertex type.
* `vertexIds`: A single vertex ID or a list of vertex IDs.
* `select`: Comma separated list of vertex attributes to be retrieved.

#### Returns:

The (selected) details of the (matching) vertex instances as pandas DataFrame.

## getVertexDataframeById()

`getVertexDataframeById(vertexType: str, vertexIds: Union[int, str, list], select: str = "") → pd.DataFrame`

DEPRECATED

Use `getVertexDataFrameById()` instead.

## getVertexStats()

`getVertexStats(vertexTypes: Union[str, list], skipNA: bool = False) → dict`

Returns vertex attribute statistics.

#### Parameters:

* `vertexTypes`: A single vertex type name or a list of vertex types names or "\*" for all vertex types.
* `skipNA`: Skip those non-applicable vertices that do not have attributes or none of their attributes have statistics gathered.

#### Returns:

A dictionary of various vertex stats for each vertex type specified.

#### Endpoint:

* `POST /builtins/{graph_name}`See [Run built-in functions](https://www.tigergraph.com/docs/tigergraph-server/4.3/API/built-in-endpoints.md#_run_built_in_functions_on_graph)

## delVertices()

`delVertices(vertexType: str, where: str = "", limit: str = "", sort: str = "", permanent: bool = False, timeout: int = 0) → int`

Deletes vertices from graph.

**Note**: The primary ID of a vertex instance is not an attribute. A primary ID cannot be used in`select`, `where` or `sort` parameters (unless the `WITH primary_id_as_attribute` clause was used when the vertex type was created).  
Use `delVerticesById()` if you need to retrieve vertices by their primary ID.

#### Parameters:

* `vertexType`: The name of the vertex type.
* `where`: Comma separated list of conditions that are all applied on each vertex' attributes. The conditions are in logical conjunction (i.e. they are "AND'ed" together).
* `sort`: Comma separated list of attributes the results should be sorted by. Must be used with `limit`.
* `limit`: Maximum number of vertex instances to be returned (after sorting). Must be used with `sort`.
* `permanent`: If true, the deleted vertex IDs can never be inserted back, unless the graph is dropped or the graph store is cleared. timeout: Time allowed for successful execution (0 = no limit, default).

#### Returns:

A single number of vertices deleted.

The primary ID of a vertex instance is NOT an attribute, thus cannot be used in above arguments.

#### Endpoint:

* `DELETE /graph/{graph_name}/vertices/{vertex_type}`See [Delete vertices](https://www.tigergraph.com/docs/tigergraph-server/4.3/API/built-in-endpoints.md#_delete_vertices)

## delVerticesById()

`delVerticesById(vertexType: str, vertexIds: Union[int, str, list], permanent: bool = False, timeout: int = 0) → int`

Deletes vertices from graph identified by their ID.

#### Parameters:

* `vertexType`: The name of the vertex type.
* `vertexIds`: A single vertex ID or a list of vertex IDs.
* `permanent`: If true, the deleted vertex IDs can never be inserted back, unless the graph is dropped or the graph store is cleared.
* `timeout`: Time allowed for successful execution (0 = no limit, default).

#### Returns:

A single number of vertices deleted.

#### Endpoint:

* `DELETE /graph/{graph_name}/vertices/{vertex_type}/{vertex_id}`See [Delete a vertex](https://www.tigergraph.com/docs/tigergraph-server/4.3/API/built-in-endpoints.md#_delete_a_vertex)

## vertexSetToDataFrame()

`vertexSetToDataFrame(vertexSet: list, withId: bool = True, withType: bool = False) → pd.DataFrame`

Converts a vertex set to Pandas DataFrame.

Vertex sets are used for both the input and output of `SELECT` statements. They contain instances of vertices of the same type. For each vertex instance, the vertex ID, the vertex type and the (optional) attributes are present under the `v_id`, `v_type` and `attributes` keys, respectively.  
See an example in `edgeSetToDataFrame()`.

A vertex set has this structure (when serialised as JSON):

```json
[
{
"v_id": <vertex_id>,
"v_type": <vertex_type_name>,
"attributes":
{
"attr1": <value1>,
"attr2": <value2>,
⋮
}
},
⋮
]
```

For more information on vertex sets see [Vertex set variables](https://www.tigergraph.com/docs/gsql-ref/4.3/querying/declaration-and-assignment-statements.md#_vertex_set_variables).

#### Parameters:

* `vertexSet`: A JSON array containing a vertex set in the format returned by queries (see below).
* `withId`: Whether to include vertex primary ID as a column.
* `withType`: Whether to include vertex type info as a column.

#### Returns:

A pandas DataFrame containing the vertex attributes (and optionally the vertex primary ID and type).
