pyTigerGraph 0.0.5.3

Library to connect to TigerGraph databases

Getting Started

To download pyTigerGraph, simply run: pip install pyTigerGraph Once the package installs, you can import it and instantiate a connection to your database:

import pyTigerGraph as tg

conn = tg.TigerGraphConnection(host="<hostname>", graphname="<graph_name>", username="<username>", password="<password>", apiToken="<api_token>")

If your database is not using the standard ports (or they are mapped), you can use the following arguments to specify those:

• restppPort (default 9000): REST++ API port
• gsPort (default: 14240): GraphStudio port

Authentication

If user authentication is enabled in the TigerGraph database, then username and password need to be specified when the connection is established. If you already have an API authorisation token, specify that one as well. Alternatively, if you know a secret (created previously in the database), you can request a token via the getToken function and use it during the session.

If user authentication is not anebled, then username, password and authorisation token are not used (i.e. the database is insecure). This is only acceptable in case of development or study environments.

The username and password default to the TigerGraph default username and password, which are tigergraph. In case of user authentication enabled, the password can't be tigergraph thus you need to specify the correct one. Furthermore, it is recommended not to use the tigergraph user for anything other than system administration. Instead, create additional users and grant them the appropriate privileges through roles, then use those users to access the database.

The functions

Common arguments used in methods:

• vertexType, sourceVertexType, targetVertexType: The name of a vertex type in the graph. Use getVertexTypes to fetch the list of vertex types currently in the graph.
• vertexId, sourceVertexId, targetVertexId: The primary ID of a vertex instance (of the appropriate data type).
• edgeType: The name of the edge type in the graph. Use getEdgeTypes to fetch the list of edge types currently in the graph.

Schema related functions getSchema getUDTs getUDT upsertData Query related functions runInstalledQuery runInterpretedQuery

Vertex related functions getVertexTypes getVertexType getVertexCount upsertVertex upsertVertices getVertices getVerticesById getVertexStats delVertices delVerticesById

Edge related functions getEdgeTypes getEdgeType getEdgeCount upsertEdge upsertEdges getEdges getEdgeStats delEdges

Token management getToken refreshToken deleteToken Other functions echo getEndpoints getStatistics getVersion getVer getLicenseInfo

Schema related functions

getSchema

getSchema(udts=True)

Retrieves the schema (all vertex and edge type and - if not disabled - the User Defined Type details) of the graph.

Documentation: GET /gsqlserver/gsql/schema

getUDTs

getUDTs()

Returns the list of User Defined Types (names only).

getUDT

getUDT(udtName)

Returns the details of a specific User Defined Type.

upsertData

upsertData(data)

Upserts data (vertices and edges) from a JSON document or equivalent object structure.

Documentation: POST /graph

Vertex related functions

getVertexTypes

getVertexTypes()

Returns the list of vertex type names of the graph.

getVertexType

getVertexType(vertexType)

Returns the details of the specified vertex type.

getVertexCount

getVertexCount(vertexType, where="")

Return the number of vertices.

Arguments:

• 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).

Uses:

• If vertexType = "*": vertex count of all vertex types (where cannot be specified in this case)
• If vertexType is specified only: vertex count of the given type
• If vertexType and where are specified: vertex count of the given type after filtered by where condition(s)

See documentation for valid values of where condition.

Returns a dictionary of <vertex_type>: <vertex_count> pairs.

Documentation: GET /graph/{graph_name}/vertices and POST /builtins

upsertVertex

upsertVertex(vertexType, vertexId, attributes=None)

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.

The attributes argument is expected to be a dictionary in this format:

{<attribute_name>, <attribute_value>|(<attribute_name>, <operator>), …}

Example:

{"name": "Thorin", "points": (10, "+"), "bestScore": (67, "max")}

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

Documentation: POST /graph

upsertVertices

upsertVertices(vertexType, vertices)

Upserts multiple vertices (of the same type).

See the description of upsertVertex for generic information.

The vertices argument is expected to be a list of tuples in this format:

[
  (<vertex_id>, {<attribute_name>, <attribute_value>|(<attribute_name>, <operator>), …}),
  ⋮
]

Example:

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

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

Documentation: POST /graph

getVertices

getVertices(vertexType, select="", where="", limit="", sort="", timeout=0)

Retrieves vertices of the given vertex type.

Arguments:

• select: Comma separated list of vertex attributes to be retrieved or omitted.
• 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).
• limit: Maximum number of vertex instances to be returned (after sorting).
• sort: Comma separated list of attributes the results should be sorted by.

NOTE: The primary ID of a vertex instance is NOT an attribute, thus cannot be used in above arguments. Use getVerticesById if you need to retrieve by vertex ID.

Documentation: GET /graph/{graph_name}/vertices

getVerticesById

getVerticesById(vertexType, vertexIds)

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

Arguments

• vertexIds: A single vertex ID or a list of vertex IDs.

Documentation: GET /graph/{graph_name}/vertices

getVertexStats

getVertexStats(vertexTypes, skipNA=False)

Returns vertex attribute statistics.

Arguments:

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

Documentation: POST /builtins

delVertices

delVertices(vertexType, where="", limit="", sort="", permanent=False, timeout=0)

Deletes vertices from graph.

Arguments:

• 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).
• limit: Maximum number of vertex instances to be returned (after sorting). Must be used with sort.
• sort: Comma separated list of attributes the results should be sorted by. Must be user with limit.
• 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).

NOTE: The primary ID of a vertex instance is NOT an attribute, thus cannot be used in above arguments. Use delVerticesById if you need to delete by vertex ID.

Returns a single number of vertices deleted.

Documentation: DELETE /graph/{graph_name}/vertices

delVerticesById

delVerticesById(vertexType, vertexIds, permanent=False, timeout=0)

Deletes vertices from graph identified by their ID.

Arguments:

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

Documentation: DELETE /graph/{graph_name}/vertices

Edge related functions

getEdgeTypes

getEdgeTypes()

Returns the list of edge type names of the graph.

getEdgeType

getEdgeType(typeName)

Returns the details of vertex type.

getEdgeCount

getEdgeCount(sourceVertexType=None, sourceVertexId=None, edgeType=None, targetVertexType=None, targetVertexId=None, where="")

Returns the number of edges.

Arguments:

• where: Comma separated list of conditions that are all applied on each edge's attributes. The conditions are in logical conjunction (i.e. they are "AND'ed" together).

Uses:

• If edgeType = "*": edge count of all edge types (no other arguments can be specified in this case).
• If edgeType is specified only: edge count of the given edge type.
• If sourceVertexType, edgeType, targetVertexType are specified: edge count of the given edge type between source and target vertex types.
• If sourceVertexType, sourceVertexId are specified: edge count of all edge types from the given vertex instance.
• If sourceVertexType, sourceVertexId, edgeType are specified: edge count of all edge types from the given vertex instance.
• If sourceVertexType, sourceVertexId, edgeType, where are specified: the edge count of the given edge type after filtered by where condition.

If targetVertexId is specified, then targetVertexType must also be specified. If targetVertexType is specified, then edgeType must also be specified.

Returns a dictionary of <edge_type>: <edge_count> pairs.

Documentation: GET /graph/{graph_name}/edges and POST /builtins

upsertEdge

upsertEdge(sourceVertexType, sourceVertexId, edgeType, targetVertexType, targetVertexId, attributes={})

Upserts an edge.

Data is upserted:

• If edge is not yet present in graph, it will be created (see special case below).
• If it's already in the graph, it is updated with the values specified in the request. An optional operator controls how the attributes are updated.

The attributes argument is expected to be a dictionary in this format:

{<attribute_name>, <attribute_value>|(<attribute_name>, <operator>), …}

Example:

{"visits": (1482, "+"), "max_duration": (371, "max")}

Returns a single number of accepted (successfully upserted) edges (0 or 1).

Note: If operator is "vertex_must_exist" then edge will only be created if both vertex exists in graph. Otherwise missing vertices are created with the new edge.

Documentation: POST /graph

upsertEdges

upsertEdges(sourceVertexType, edgeType, targetVertexType, edges)

Upserts multiple edges (of the same type).

See the description of upsertEdge for generic information.

The edges argument is expected to be a list in of tuples in this format:

[
  (<source_vertex_id>, <target_vertex_id>, {<attribute_name>: <attribute_value>|(<attribute_name>, <operator>), …})
  ⋮
]

Example:

[
  (17, "home_page", {"visits": (35, "+"), "max_duration": (93, "max")}),
  (42, "search", {"visits": (17, "+"), "max_duration": (41, "max")}),
]

Returns a single number of accepted (successfully upserted) edges (0 or positive integer).

Documentation: POST /graph

getEdges

getEdges(sourceVertexType, sourceVertexId, edgeType=None, targetVertexType=None, targetVertexId=None, select="", where="", limit="", sort="", timeout=0)

Retrieves edges of the given edge type.

Only sourceVertexType and sourceVertexId are required. If targetVertexId is specified, then targetVertexType must also be specified. If targetVertexType is specified, then edgeType must also be specified.

Arguments:

• select: Comma separated list of edge attributes to be retrieved or omitted.
• where: Comma separated list of conditions that are all applied on each edge's attributes. The conditions are in logical conjunction (i.e. they are "AND'ed" together).
• limit: Maximum number of edge instances to be returned (after sorting).
• sort: Comma separated list of attributes the results should be sorted by.

Documentation: GET /graph/{graph_name}/vertices

getEdgeStats

getEdgeStats(edgeTypes, skipNA=False)

Returns edge attribute statistics.

Arguments:

• edgeTypes: A single edge type name or a list of edges types names or '*' for all edges types.
• skipNA: Skip those non-applicable edges that do not have attributes or none of their attributes have statistics gathered.

Documentation: POST /builtins

delEdges

delEdges(sourceVertexType, sourceVertexId, edgeType=None, targetVertexType=None, targetVertexId=None, where="", limit="", sort="", timeout=0)

Deletes edges from the graph.

Only sourceVertexType and sourceVertexId are required. If targetVertexId is specified, then targetVertexType must also be specified. If targetVertexType is specified, then edgeType must also be specified.

Arguments:

• where: Comma separated list of conditions that are all applied on each edge's attributes. The conditions are in logical conjunction (i.e. they are "AND'ed" together).
• limit: Maximum number of edge instances to be returned (after sorting).
• sort: Comma separated list of attributes the results should be sorted by.
• timeout: Time allowed for successful execution (0 = no limit, default).

Returns a dictionary of <edge_type>: <deleted_edge_count> pairs.

Documentation: DELETE /graph/{/graph_name}/edges

Query related functions

runInstalledQuery

runInstalledQuery(queryName, params=None, timeout=16000, sizeLimit=32000000)

Runs an installed query.

The query must be already created and installed in the graph. Use getEndpoints(dynamic=True) or GraphStudio to find out the generated endpoint URL of the query, but only the query name needs to be specified here.

Arguments:

• params: A string of param1=value1&param2=value2 format or a dictionary.
• timeout: Maximum duration for successful query execution.
• sizeLimit: Maximum size of response (in bytes).

Documentation: POST /query/{graph_name}/<query_name>

runInterpretedQuery

runInterpretedQuery(queryText, params=None)

Runs an interpreted query.

You must provide the query text in this format:

INTERPRET QUERY (<params>) FOR GRAPH <graph_name> {
   <statements>
}'

Arguments:

• params: A string of param1=value1&param2=value2 format or a dictionary.

Documentation: POST /gsqlserver/interpreted_query

Token management

getToken

getToken(secret, setToken=True, lifetime=None)

Requests an authorisation token.

This function returns a token only if REST++ authentication is enabled. If not, an exception will be raised.

Arguments:

• secret: The secret (string) generated in GSQL using CREATE SECRET.
• setToken: Set the connection's API token to the new value (default: True).
• lifetime: Duration of token validity (in secs, default 30 days = 2,592,000 secs).

Returns a tuple of (<new_token>, <exporation_timestamp_unixtime>, <expiration_timestamp_ISO8601>). Return value can be ignored.

Note: expiration timestamp's time zone might be different from your computer's local time zone.

Documentation: GET /requesttoken

refreshToken

refreshToken(secret, token=None, lifetime=2592000)

Extends a token's lifetime.

This function works only if REST++ authentication is enabled. If not, an exception will be raised.

Arguments:

• secret: The secret (string) generated in GSQL using CREATE SECRET.
• token: The token requested earlier. If not specified, refreshes current connection's token.
• lifetime: Duration of token validity (in secs, default 30 days = 2,592,000 secs).

Returns a tuple of (<token>, <exporation_timestamp_unixtime>, <expiration_timestamp_ISO8601>). Return value can be ignored. Raises exception if specified token does not exists.

Note:

• New expiration timestamp will be now + lifetime seconds, not current expiration timestamp + lifetime seconds.
• Expiration timestamp's time zone might be different from your computer's local time zone.

Documentation: PUT /requesttoken

deleteToken

deleteToken(secret, token)

Deletes a token.

This function works only if REST++ authentication is enabled. If not, an exception will be raised.

Arguments:

• secret: The secret (string) generated in GSQL using CREATE SECRET.
• token: The token requested earlier. If not specified, deletes current connection's token, so be careful.
• skipNA: Don't raise exception if specified token does not exist.

Returns True if deletion was successful or token did not exist but skipNA was True; raises exception otherwise.

Documentation: DELETE /requesttoken

Other functions

echo

echo()

Pings the database.

Expected return value is "Hello GSQL"

Documentation: GET /echo and POST /echo

getEndpoints

getEndpoints(builtin=False, dynamic=False, static=False)

Lists the REST++ endpoints and their parameters.

Arguments:

• builtin: TigerGraph provided REST++ endpoints.
• dymamic: Endpoints for user installed queries.
• static: Static endpoints.

If none of the above arguments are specified, all endpoints are listed. Documentation: GET /endpoints

getStatistics

getStatistics(seconds=10, segment=10)

Arguments:

• seconds: The duration of statistic collection period (the last n seconds before the function call).
• segments: The number of segments of the latency distribution (shown in results as LatencyPercentile). By default, segments is 10, meaning the percentile range 0-100% will be divided into ten equal segments: 0%-10%, 11%-20%, etc. Segments must be [1, 100].

Retrieves real-time query performance statistics over the given time period.

Documentation: GET /statistics

getVersion

getVersion()

Retrieves the git versions of all components of the system.

Documentation: GET /version

getVer

getVer(component="product", full=False)

Arguments:

• component: One of TigerGraph's components (e.g. product, gpe, gse).

Gets the version information of specific component.

Get the full list of components using getVersion.

getLicenseInfo

getLicenseInfo()

Returns the expiration date and remaining days of the license.

In case of evaluation/trial deployment, an information message and -1 remaining days are returned.

Compatibility

This package has been tested with TigerGraph 2.5.2 and 2.6