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

[View as HTML](https://www.tigergraph.com/docs/pytigergraph/1.8/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).

## Methods

### 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, atomic: bool = False) → 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). \* `atomic`: The request is an atomic transaction. An atomic transaction means that updates to the database contained in the request are all-or-nothing: either all changes are successful, or none are successful. This uses the `gsql-atomic-level` header, and sets the value to `atomic` if `True`, and `nonatomic` if `False`. Default is `False`.

#### 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, atomic: bool = False) → 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.
* `atomic`: The request is an atomic transaction. An atomic transaction means that updates to the database contained in the request are all-or-nothing: either all changes are successful, or none are successful. This uses the `gsql-atomic-level` header, and sets the value to `atomic` if `True`, and `nonatomic` if `False`. Default is `False`.

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

### delVerticesByType()

`delVerticesByType(vertexType: str, permanent: bool = False, ack: str = "none") → int`

Deletes all vertices of the specified type.

#### Parameters:

* `vertexType`: The name of the vertex type.
* `permanent`: If true, the deleted vertex IDs can never be inserted back, unless the graph is dropped or the graph store is cleared.
* `ack`: If the parameter is set to "none", the delete operation doesn't need to get acknowledgment from any GPE. If it is set to "all" (default), the operation needs to get acknowledgment from all GPEs. Other values will raise an error.

#### Returns:

A single number of vertices deleted.

#### Usage:

```none
pyconn.delVerticesByType("Person")
```

### vertexSetToDataFrame()

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

Converts a vertex set (dictionary) to a pandas DataFrame.

#### Parameters:

* `vertexSet`: The vertex set to convert.
* `withId`: Should the vertex ID be included in the DataFrame?
* `withType`: Should the vertex type be included in the DataFrame?

#### Returns:

The vertex set as a pandas DataFrame.
