OPG4Py Pgql

opg4py.graph_server.GraphServer: Wrapper class for oracle.pg.rdbms.GraphServer

opg4py.graph_server.generate_token(base_url, username, password)

Generates a new authentication token.

Parameters

base_url – the base URL in the format host [ : port][ /path] of the remote graph server.
username – the Database username to use for authentication.
password – the Database password to use for authentication.

Returns

the newly generated authentication token

opg4py.graph_server.get_embedded_instance()

Connects to an embedded graph server. An embedded graph server runs inside the client JVM.

Returns: a handle to the embedded graph server

opg4py.graph_server.get_instance(base_url, username, password, refresh_time_before_token_expiry=-1, *, kerberos_ticket_path=None)

Connects to a remote graph server.

Parameters

base_url (str) – the base URL in the format host [ : port][ /path] of the remote graph server. If base_url is None, the default will be used which points to embedded graph server instance.
username (str) – the Database username to use for authentication.
password (str) – the Database password to use for authentication.
refresh_time_before_token_expiry (int) –
the time in seconds to refresh the token automatically before expires.

Deprecated since version 23.1.0: moved refresh_time_before_token_expiry value to the pgx.conf (refresh_time_before_token_expiry_seconds)
kerberos_ticket_path (Optional[str]) – the kerberos ticket to be used for authentication.

Returns

a handle to the remote graph server

Return type

ServerInstance

opg4py.graph_server.reauthenticate(instance, username, password)

Re-authenticates an existing ServerInstance object with a remote graph server.

Parameters

instance – the PGX instance on which the session is going to reauthenticate.
username – the Database username to use for authentication.
password – the Database password to use for authentication.

Returns

the newly generated authentication token

Python API for the PGQL-on-RDBMS client.

class opg4py.pgql.PgqlConnection(java_pgql_connection)

Bases: object

Wrapper class for oracle.pg.rdbms.pgql.PgqlConnection.

clear_graph_metadata_cache(): Clear the cache that stores graph metadata.

clear_translation_cache(): Clear the cache that stores translations.

close(): Free the resources of the internal JDBC connection.

create_statement()

Creates a new PgqlStatement object, which is used to execute PGQL queries.

Returns: a new PgqlStatement object that can be used to perform PGQL queries

disable_graph_metadata_cache(): Disable the cache that stores graph metadata.

disable_translation_cache(): Disable the cache that stores translations.

enable_graph_metadata_cache(): Enable the cache that stores graph metadata.

enable_translation_cache(): Enable the cache that stores translations.

static get_connection(java_sql_connection)

Factory method to get PgqlConnection instance.

Parameters: java_sql_connection – a JDBC connection
Returns: a PgqlConnection instance

get_graph()

Get the graph name on which PGQL queries will be executed for this connection.

Returns: the graph name for this connection

get_jdbc_connection()

Get the JDBC connection that is used to execute PGQL queries.

Returns: the connection

get_schema()

Get the schema name that will be used to execute PGQL queries with this connection.

If the schema has not been set, the schema from JDBC connection is returned.

Returns: the schema set for this connection

Throws:: PgqlToSqlException - if a database access error occurs or this method is called on a closed connection

prepare_statement(pgql, timeout=0, parallel=0, dynamicSampling=2, maxResults=-1, matchOptions=None, options=None)

Creates a new PgqlPreparedStatement object, which represents a pre-compiled PGQL statement.

Parameters

pgql – the PGQL query to compile
timeout – the number of seconds for query execution to finish
parallel – the degree of parallelism to use for query and modify execution
dynamicSampling – the value for dynamic sampling
maxResults – the maximum number of rows returned
matchOptions – additional options used to influence query translation and execution
options – additional options used to influence modify translation and execution

Returns

a PgqlPreparedStatement object that can be used to efficiently execute the same query multiple times

set_graph(graph)

Sets the graph name on which PGQL queries will be executed for this connection.

Parameters: graph – the name of the graph

set_graph_metadata_cache_max_capacity(max_capacity)

Set max capacity value for the graph metadata cache

Parameters: max_capacity – value for max capacity

set_schema(schema)

Sets the schema name that will be used to execute PGQL queries with this connection.

Parameters: schema – the name of the schema

set_translation_cache_max_capacity(max_capacity)

Set max capacity value for the translation cache

Parameters: max_capacity – value for max capacity

class opg4py.pgql.PgqlPreparedStatement(java_pgql_prepared_statement)

Bases: PgqlStatement

Wrapper class for oracle.pg.rdbms.pgql.PgqlPreparedStatement.

execute(parallel=0, dynamic_sampling=2, match_options=None, options=None)

Executes a PGQL Query, Modify or Create/Drop operation on this instance’s property graph.

Supported query options (matchOptions) are the same as those for executeQuery.

Supported modify options are:

STREAMING=T Use result sets instead of temporary tables to perform the update.

AUTO_COMMIT=F Do not commit after performing the modify operation.

DELETE_CASCADE=F Do not delete incoming/outgoing edges when deleting a vertex.

Parameters

parallel – the degree of parallelism to use for query and update execution
dynamic_sampling – the value for dynamic sampling
match_options – additional options used to influence query translation and execution
options – additional options used to influence modify translation and execution

Returns

True if the provided PGQL query is a select, false for other statements

Throws:: PgqlToSqlException - if a server-side error occurs during translation or SQL execution oracle.pgql.lang.PgqlException - if a server-side error occurs or method is called on a closed Statement

execute_query(timeout=0, parallel=0, dynamic_sampling=2, max_results=-1, options=None)

Translates this PGQL statement into a SQL statement and executes it against this instance’s property graph.

Supported query options are:

USE_RW=F Use CONNECT BY instead of recursive WITH for unbounded path traversals

MAX_PATH_LEN=n Traverse at most n hops when evaluating unbounded path traversals

EDGE_SET_PARTIAL=T Fetch properties for each start and end vertex found when reading edges from the query result

Parameters

timeout – the number of seconds for query execution to finish
parallel – the degree of parallelism to use for query execution
dynamic_sampling – the value for dynamic sampling
max_results – the maximum number of rows returned
options – additional options used to influence query translation and execution

Returns

a PgqlResultSet object with the result of the provided PGQL query

Throws:: PgqlToSqlException - if a server-side error occurs during translation or SQL execution oracle.pgql.lang.PgqlException - if a server-side error occurs or method is called on a closed Statement

set_array(param_index, value)

Sets the designated parameter to the given Java List value.

Parameters: param_index – the first parameter is 1, the second is 2, …
Param: value: the parameter value

set_boolean(param_index, value)

Sets the designated parameter to the given Java boolean value.

Parameters: param_index – the first parameter is 1, the second is 2, …
Param: value: the parameter value

set_double(param_index, value)

Sets the designated parameter to the given Java double value.

Parameters: param_index – the first parameter is 1, the second is 2, …
Param: value: the parameter value

set_float(param_index, value)

Sets the designated parameter to the given Java float value.

Parameters: param_index – the first parameter is 1, the second is 2, …
Param: value: the parameter value

set_int(param_index, value)

Sets the designated parameter to the given Java int value.

Parameters: param_index – the first parameter is 1, the second is 2, …
Param: value: the parameter value

set_long(param_index, value)

Sets the designated parameter to the given Java long value.

Parameters: param_index – the first parameter is 1, the second is 2, …
Param: value: the parameter value

set_string(param_index, value)

Sets the designated parameter to the given Java String value.

Parameters: param_index – the first parameter is 1, the second is 2, …
Param: value: the parameter value

set_timestamp(param_index, value)

Sets the designated parameter to the given Java Timestamp value.

Timestamp values are assumed to be in Coordinated Universal Time (UTC).

Parameters: param_index – the first parameter is 1, the second is 2, …
Param: value: the parameter value

class opg4py.pgql.PgqlResultSet(java_pgql_result_set)

Bases: object

Wrapper class for oracle.pg.rdbms.pgql.PgqlResultSet.

absolute(row)

Move the cursor to the given row number in this ResultSet object.

If the row number is positive, the cursor moves to the given row number with respect to the beginning of the result set. The first row is 1, so absolute(1) moves the cursor to the first row.

If the row number is negative, the cursor moves to the given row number with respect to the end of the result set. So absolute(-1) moves the cursor to the last row.

Parameters: row – Row to move to
Returns: True if the cursor is moved to a position in the ResultSet object; False if the cursor is moved before the first or after the last row
Return type: bool

after_last()

Place the cursor after the last row.

Return type: None

before_first()

Set the cursor before the first row.

Return type: None

close()

Free resources on the server taken up by this result_set object.

Return type: None

fetchall()

Fetch all (remaining) rows of a query result, returning them as a list of tuples. An empty list is returned if no more rows are available.

Returns: A list of tuples with all (remaining) rows of a query result
Return type: List[tuple]

fetchmany(num_rows=1)

Fetch the next set of rows of a query result, returning a list of tuples. An empty list is returned if no more rows are available.

Returns: A list of tuples with the next set of rows of a query result
Parameters: num_rows (int) –
Return type: List[tuple]

fetchone()

Fetch the next row of a query result set, returning a single tuple or None when no more data is available.

Returns: A single tuple with the next row of a query result
Return type: tuple

first()

Move the cursor to the first row in the result set.

Returns: True if the cursor points to a valid row; False if the result set does not have any results
Return type: bool

get(element)

Get the value of the designated element by element index or name.

Parameters: element (Union[str, int]) – Integer or string representing index or name
Returns: Content of cell
Return type: Any

get_boolean(element)

Get the value of the designated element by element index or name as a Boolean.

Parameters: element (Union[str, int]) – Integer or String representing index or name
Returns: Boolean
Return type: Optional[bool]

get_date(element)

Get the value of the designated element by element index or name as a datetime Date.

Parameters: element (Union[str, int]) – Integer or String representing index or name
Returns: datetime.date
Return type: Optional[date]

get_float(element)

Get the value of the designated element by element index or name as a Float.

Parameters: element (Union[str, int]) – Integer or String representing index or name
Returns: Float
Return type: Optional[float]

get_integer(element)

Get the value of the designated element by element index or name as an Integer.

Parameters: element (Union[str, int]) – Integer or String representing index or name
Returns: Integer
Return type: Optional[int]

get_list(element)

Get the value of the designated element by element index or name as a List.

Parameters: element (Union[str, int]) – Integer or String representing index or name
Returns: List
Return type: Optional[List[str]]

get_metadata()

Get the ResultSet MetaData.

Returns: PgqlResultSetMetaData
Return type: PgqlResultSetMetaData

get_row(row)

Get row from result_set.

Parameters: row – Row index
Return type: Any

get_slice(start, stop, step=1)

Get slice from result_set.

Parameters

start (int) – Start index
stop (int) – Stop index
step (int) – Step size

Return type

List[list]

get_string(element)

Get the value of the designated element by element index or name as a String.

Parameters: element (Union[str, int]) – Integer or String representing index or name
Returns: String
Return type: Optional[str]

get_time(element)

Get the value of the designated element by element index or name as a datetime Time.

Parameters: element (Union[str, int]) – Integer or String representing index or name
Returns: datetime.time
Return type: Optional[time]

get_time_with_timezone(element)

Get the value of the designated element by element index or name as a datetime Time with timezone.

Parameters: element (Union[str, int]) – Integer or String representing index or name
Returns: datetime.time
Return type: Optional[time]

get_timestamp(element)

Get the value of the designated element by element index or name as a Datetime.

Parameters: element (Union[str, int]) – Integer or String representing index or name
Returns: datetime.datetime
Return type: Optional[datetime]

get_timestamp_with_timezone(element)

Get the value of the designated element by element index or name as a Datetime with timezone.

Parameters: element (Union[str, int]) – Integer or String representing index or name
Returns: datetime.datetime
Return type: Optional[datetime]

get_value_type(element)

Get the type of value of the designated element by element index or name as an Integer.

Parameters: element – Integer or String representing index or name
Returns: Integer
Return type: int

get_vertex_labels(element)

Get the value of the designated element by element index or name as a list of labels.

Parameters: element (Union[str, int]) – Integer or String representing index or name
Returns: list
Return type: List[str]

last()

Move the cursor to the last row in the result set.

Returns: True if the cursor points to a valid row; False if the result set does not have any results
Return type: bool

next()

Move the cursor forward one row from its current position.

Returns: True if the cursor points to a valid row; False if the new cursor is positioned after the last row
Return type: bool

previous()

Move the cursor to the previous row from its current position.

Returns: True if the cursor points to a valid row; False if the new cursor is positioned before the first row
Return type: bool

print(file=None, num_results=1000, start=0)

Print the result set.

Parameters

file (Optional[TextIO]) – File to which results are printed (default is sys.stdout)
num_results (int) – Number of results to be printed
start (int) – Index of the first result to be printed

Return type

None

relative(rows)

Move the cursor a relative number of row with respect to the current position.

Note a negative number will move the cursor backwards.

Note: Calling relative(1) is equal to next() and relative(-1) is equal to previous. Calling relative(0) is possible when the cursor is positioned at a row, not when it is positioned before the first or after the last row. However, relative(0) will not update the position of the cursor.

Parameters: rows – Relative number of rows to move from current position
Returns: True if the cursor is moved to a position in the ResultSet object; False if the cursor is moved before the first or after the last row
Return type: bool

to_pandas()

Convert to pandas DataFrame (this method requires pandas).

Returns: PgqlResultSet as a Pandas Dataframe

class opg4py.pgql.PgqlResultSetMetaData(java_pgql_result_set_metadata)

Bases: object

Wrapper class for oracle.pgql.lang.ResultSetMetaData.

get_column_count()

Get the total number of columns in the query result.

Returns: the total number of columns

get_column_name(column)

Get the name of the column at the given offset starting from 1.

Parameters: column – the offset of the column, numbering starts from 1
Returns: the column name

class opg4py.pgql.PgqlSqlQueryTrans(java_pgql_sql_query_trans)

Bases: PgqlSqlTrans

Wrapper class for oracle.pg.rdbms.pgql.PgqlSqlQueryTrans.

get_return_types()

Get an array of column descriptors for the result columns in the query result.

Returns: result column descriptions

get_sql_bv_list()

Get a list of Bind Values to be used with this SQL translation.

The first element in the list should be set at position 1 in a JDBC PreparedStatement created from this SQL translation.

Returns: the list of bind values for this query translation

get_sql_translation()

Get the SQL string for the PGQL to SQL translation.

Returns: the SQL query string

class opg4py.pgql.PgqlSqlTrans(java_pgql_sql_trans)

Bases: object

Wrapper class for oracle.pg.rdbms.pgql.PgqlSqlTrans.

get_translation_type()

Get the type for the PGQL to SQL translation.

Returns: a PgqlSqlTrans.TranslationType object with the SQL translation type

class opg4py.pgql.PgqlStatement(java_pgql_statement)

Bases: object

Wrapper class for oracle.pg.rdbms.pgql.PgqlStatement.

cancel()

Allows to cancel currently running execute operation.

Note that cancel does not rollback already executed modifications.

Throws: oracle.pgql.lang.PgqlException - When an error occurs while canceling current operation.

close()

Releases this PgqlStatment’s database and JDBC resources.

Closing this PgqlStatement will close all PgqlResultSets that were created from it.

Throws: oracle.pgql.lang.PgqlException

execute(pgql, parallel=0, dynamic_sampling=2, match_options=None, options=None)

Executes a PGQL Query, Modify or Create/Drop operation on this instance’s property graph.

Supported query options (matchOptions) are the same as those for executeQuery.

Supported modify options are:

STREAMING=T Use result sets instead of temporary tables to perform the update.

AUTO_COMMIT=F Do not commit after performing the modify operation.

DELETE_CASCADE=F Do not delete incoming/outgoing edges when deleting a vertex.

Parameters

pgql – the PGQL modify to execute
parallel – the degree of parallelism to use for query and update execution
dynamic_sampling – the value for dynamic sampling
match_options – additional options used to influence query translation and execution
options – additional options used to influence modify translation and execution

Returns

True if the provided PGQL query is a select, false for other statements

Throws:: PgqlToSqlException - if a server-side error occurs during translation or SQL execution oracle.pgql.lang.PgqlException - if a server-side error occurs or method is called on a closed Statement

execute_query(pgql, timeout=0, parallel=0, dynamic_sampling=2, max_results=-1, options=None)

Translates this PGQL statement into a SQL statement and executes it against this instance’s property graph.

Supported query options are:

USE_RW=F Use CONNECT BY instead of recursive WITH for unbounded path traversals

MAX_PATH_LEN=n Traverse at most n hops when evaluating unbounded path traversals

EDGE_SET_PARTIAL=T Fetch properties for each start and end vertex found when reading edges from the query result

Parameters

pgql – the PGQL query to execute
timeout – the number of seconds for query execution to finish
parallel – the degree of parallelism to use for query execution
dynamic_sampling – the value for dynamic sampling
max_results – the maximum number of rows returned
options – additional options used to influence query translation and execution

Returns

a PgqlResultSet object with the result of the provided PGQL query

Throws:: PgqlToSqlException - if a server-side error occurs during translation or SQL execution oracle.pgql.lang.PgqlException - if a server-side error occurs or method is called on a closed Statement

get_batch_size()

Get the number of commands that should be batched when executing updates.

Returns: the update batch size

get_fetch_size()

Get the number of rows that should be fetched from the database when more rows are needed for a query result.

Returns: the query fetch size

get_modify_count()

Get the number of rows that were modified by last execute operation.

Returns: The number of rows modified

get_result_set()

Retrieve the current result as a PgqlResultSet object.

This method should be called only once per result.

Returns: Current result as a ResultSet object or null if the query is not a SELECT query

set_batch_size(batch_size)

Set the number of commands that should be batched when executing updates.

Parameters: batch_size – the update batch size

set_fetch_size(fetch_size)

Set the number of rows that should be fetched from the database when more rows are needed for a query result.

Parameters: fetch_size – the query fetch size

translate_query(pgql, parallel=0, dynamic_sampling=2, max_results=-1, options=None)

Translates this instance’s PGQL statement into a SQL statement.

Supported query options are:

USE_RW=F Use CONNECT BY instead of recursive WITH for unbounded path traversals

MAX_PATH_LEN=n Traverse at most n hops when evaluating unbounded path traversals

EDGE_SET_PARTIAL=T Fetch properties for each start and end vertex found when reading edges from the query result

Parameters

pgql – the PGQL query to translate
parallel – the degree of parallelism to use for query execution
dynamic_sampling – the value for dynamic sampling
max_results – the maximum number of rows returned
options – additional options used to influence query translation

Returns

a PgqlSqlTrans object with the SQL translation and column metadata for the provided PGQL query

Throws:: PgqlToSqlException - if a server-side error occurs during translation oracle.pgql.lang.PgqlException - if a server-side error occurs or method is called on a closed Statement

translate_statement(pgql, parallel=0, dynamic_sampling=2, max_results=-1, match_options=None, options=None)

Translates the given PGQL statement into a series of SQL statements.

Parameters

pgql – the PGQL statement to translate
parallel – the degree of parallelism to use for query execution
dynamic_sampling – the value for dynamic sampling
max_results – the maximum number of rows returned
match_options – additional options used to influence query translation and execution
options – additional options used to influence DDL/DML translation and execution

Returns

the SQL statements and metadata necessary to execute the provided SQL statement

Throws:: PgqlToSqlException - if a server-side error occurs during translation oracle.pgql.lang.PgqlException - if a server-side error occurs or method is called on a closed Statement

opg4py.pgql.get_connection(usr, pwd, jdbc_url)

Get a DB connection.

Parameters

usr – the DB user
pwd – the DB password
jdbc_url – the DB jdbc url

Returns

A PgqlConnection