5.2.6. xgt.Job

class xgt.Job(conn, job_response=None, python_errors=None)

Represents a user-scheduled Job.

An instance of this object is created by job-scheduling functions like xgt.Connection.run_job and xgt.Connection.schedule_job.

A Job is used as a proxy for a job in the server and allows the user to monitor its execution, possibly cancel it, and learn about its status during and after execution.

The conn parameter represents a previously established connection to the xGT server.

The job_response parameter is a single element of the array returned by the output of a job creation gRPC call. Each individual element in the array will be constructed as a separate Job object.

Methods

__init__(conn[, job_response, python_errors])

Constructor for Job.

get_data([offset, length, columns, format])

Returns results data starting at a given offset and spanning a given length.

get_data_arrow([offset, length])

Returns an Apache Arrow Table containing results data starting at a given offset and spanning a given length.

get_data_pandas([offset, length])

Returns a Pandas DataFrame containing results data starting at a given offset and spanning a given length.

get_ingest_errors([offset, length])

Returns a table of strings giving error information from ingest.

Attributes

description

A description supplied when the job was started.

end_time

Date and time when the job finished running.

error

User-friendly error message describing the reason a job failed.

error_type

Class that belongs to the XgtError hierarchy that corresponds to the original exception type thrown that caused the Job to fail.

id

Identifier of the job.

num_rows

The number of rows in the query result.

schema

The property names and types of the stored results.

start_time

Date and time when the job was scheduled.

status

Status of the job.

total_ingest_errors

The number of errors that were thrown during ingest.

total_rows

The number of rows in the query result.

total_visited_edges

The total number of edges traversed during the job.

trace

Very detailed error message for a failed job.

user

User who ran the job.

visited_edges

A dictionary mapping Cypher bound variable names to an integer giving the number of edges visited during the job for the Edge Frame referenced by the bound variable.

__init__(conn, job_response=None, python_errors=None)

Constructor for Job. Called when Job is created.

property description

A description supplied when the job was started. Usually a query.

Type:

str

property end_time

Date and time when the job finished running.

This is a formatted string that has a resolution of seconds.

Type:

str

property error

User-friendly error message describing the reason a job failed.

Type:

str

property error_type

Class that belongs to the XgtError hierarchy that corresponds to the original exception type thrown that caused the Job to fail.

Type:

object

get_data(offset=0, length=None, columns=None, format='python')

Returns results data starting at a given offset and spanning a given length.

Parameters:
  • offset (int) – Position (index) of the first row to be retrieved. Optional. Default=0.

  • length (int) – Maximum number of rows to be retrieved starting from the row indicated by offset. A value of ‘None’ means ‘all rows’ on and after the offset. Optional. Default=None.

  • columns (list of int or str) –

    The columns to retrieve. Given as a mixed list of column positions and schema column names. A value of ‘None’ means all columns. Optional. Default=None.

    New in version 1.14.0.

  • format (str) –

    Selects the data format returned: a Python list of list, a pandas Dataframe, or an Apache Arrow Table. Must be one of ‘python’, ‘pandas’, or ‘arrow’. Default=’python’.

    New in version 1.14.0.

Returns:

  • Returns one of the following if the job object represents a TQL query with

  • no RETURN clause – list of lists, pandas DataFrame, or Apache Arrow Table

  • Otherwise, returns None.

Raises:
  • ValueError – If parameter is out of bounds or invalid format given.

  • OverflowError – If data is out of bounds when converting.

get_data_arrow(offset=0, length=None)

Returns an Apache Arrow Table containing results data starting at a given offset and spanning a given length.

Deprecated since version 1.14.0: Use get_data instead.

Parameters:
  • offset (int) – Position (index) of the first row to be retrieved. Optional. Default=0.

  • length (int) – Maximum number of rows to be retrieved starting from the row indicated by offset. A value of ‘None’ means ‘all rows’ on and after the offset. Optional. Default=None.

Return type:

Apache Arrow Table

Raises:

ValueError – If parameter is out of bounds.

get_data_pandas(offset=0, length=None)

Returns a Pandas DataFrame containing results data starting at a given offset and spanning a given length.

Deprecated since version 1.14.0: Use get_data instead.

Parameters:
  • offset (int) – Position (index) of the first row to be retrieved. Optional. Default=0.

  • length (int) – Maximum number of rows to be retrieved starting from the row indicated by offset. A value of ‘None’ means ‘all rows’ on and after the offset. Optional. Default=None.

Return type:

Pandas DataFrame

Raises:

ValueError – If parameter is out of bounds.

get_ingest_errors(offset=0, length=None)

Returns a table of strings giving error information from ingest. The first thousand errors raised are retrievable this way.

Parameters:
  • offset (int) – Position (index) of the first row to be retrieved. Optional. Default=0.

  • length (int) – Maximum number of rows of errors to be retrieved starting from the row indicated by offset. A value of ‘None’ means ‘all rows’ on and after the offset. Optional. Default=None.

Returns:

  • list of str

  • If this is not an ingest job or no errors were raised, this returns None.

property id

Identifier of the job.

A 64-bit integer value that uniquely identifies a job. It is automatically incremented for each scheduled job over the lifetime of the xGT server process.

Type:

int

property num_rows

The number of rows in the query result.

New in version 1.15.0.

Type:

int

property schema

The property names and types of the stored results.

Type:

list of lists

property start_time

Date and time when the job was scheduled.

This is a formatted string that has a resolution of seconds.

Type:

str

property status

Status of the job.

Job status

Status

Description

scheduled

The state after the job has been created, but before it has started running.

running

The job is being executed.

completed

The job finished successfully.

canceled

The job was canceled.

failed

The job failed. When the job fails the error and trace properties are populated.

rollback

The job had a transactional conflict with another job and was rolled back.

unknown_job_status

The job was not found in the job history.

Type:

str

property total_ingest_errors

The number of errors that were thrown during ingest.

Type:

int

property total_rows

The number of rows in the query result.

Deprecated since version 1.15.0: Use num_rows instead.

Type:

int

property total_visited_edges

The total number of edges traversed during the job. This is the sum of the counts for all edge labels returned in visited_edges.

For the example given in the visited_edges documentation, the value of total_visited_edges would be 16.

Type:

int

property trace

Very detailed error message for a failed job.

This error message contains the friendly error message and a stack strace for the code that participated in the error.

Type:

str

property user

User who ran the job.

Type:

str

property visited_edges

A dictionary mapping Cypher bound variable names to an integer giving the number of edges visited during the job for the Edge Frame referenced by the bound variable.

An edge is “visited” when the query considers the edge as a match to one of the query path edges. Multiple Cypher variables can refer to the same edge frame.

Consider the query path ()-[a:graph_edges1]->()-[b:graph_edges2]->()-[c:graph_edges1]->() with a visited_edges result of a -> 5, b -> 7, c -> 4. In performing the query 5 edges of type a were visited, and so on. Notice that the total number of edges visited for the frame graph_edges1 is 9 while the number of edges visited for the frame graph_edges2 is 7.

Type:

dict