Vertex Functions
Functions to upsert, retrieve and delete vertices.
All functions in this module are called as methods on a TigerGraphConnection
object.
getVertexTypes()
getVertexTypes(force: bool = False) → list
Returns the list of vertex type names of the graph.
Parameter:
-
force
: IfTrue
, 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
: IfTrue
, 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. IfvertexType
== "*", 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. Setrealtime=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
andwhere
are specified: count of the instances of the given vertex type after being filtered bywhere
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 -
POST /builtins
See Run built-in functions
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:{<attribute_name>: <attribute_value>|(<attribute_name>, <operator>), …}
Example:
{"name": "Thorin", points: (10, "+"), "bestScore": (67, "max")}
For valid values of <operator>
see Operation codes.
Returns:
A single number of accepted (successfully upserted) vertices (0 or 1).
Endpoint:
-
POST /graph/{graph_name}
See 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:
[
(<vertex_id>, {<attribute_name>: <attribute_value>, …}),
(<vertex_id>, {<attribute_name>: (<attribute_value>, <operator>), …}),
⋮
]
+ Example:
[
(2, {"name": "Balin", "points": (10, "+"), "bestScore": (67, "max")}),
(3, {"name": "Dwalin", "points": (7, "+"), "bestScore": (35, "max")})
]
For valid values of <operator>
see 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
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 thegsql-atomic-level
header, and sets the value toatomic
ifTrue
, andnonatomic
ifFalse
. Default isFalse
.
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 withlimit
. -
limit
: Maximum number of vertex instances to be returned (after sorting). Must be used withsort
. -
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
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 withsort
. -
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
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
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 withlimit
. -
limit
: Maximum number of vertex instances to be returned (after sorting). Must be used withsort
. -
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
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
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:
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.