7.3.3. xgt.TableFrame

class xgt.TableFrame(conn, name, schema)

TableFrame object represent a table held on the xGT server. It can be used to retrieve information about it and should not be instantiated directly by the user. Methods that return this object: Connection.get_table_frame(), Connection.get_table_frames() and Connection.create_table_frame(). A table may also be created by a MATCH query and may contain query results.

Parameters

  • conn (Connection) – An open connection to an xGT server.

  • name (str) – Fully qualified name of the frame, including the namespace.

  • schema (list of pairs) – List of pairs associating property names with xGT data types.

Examples

>>> import xgt
>>> conn = xgt.Connection()
>>> ... run query and store results in Results
>>> t = conn.get_table_frame('career__Results')
>>> print(t.name)

Methods

__init__(conn, name, schema)

Constructor for TableFrame.

get_data([offset, length, include_row_labels])

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

get_data_pandas([offset, length, …])

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

insert(data[, row_labels, row_label_columns])

Inserts data rows.

load(paths[, headerMode, record_history, …])

Loads data from one or more CSV files specified in the list of paths.

save(path[, offset, length, headers, …])

Writes the rows from the frame to a CSV file in the path and the computer indicated by the path.

Attributes

connection

The connection used when constructing the frame.

name

Name of the frame.

num_rows

Gets the number of rows in the frame.

row_label_universe

Gets the universe of row security labels that can be attached to rows of this frame.

schema

Gets the property names and types of the frame.
__init__(conn, name, schema)

Constructor for TableFrame. Called when TableFrame is created.

property connection

The connection used when constructing the frame.

Type

Connection object

get_data(offset=0, length=None, include_row_labels=False)

Returns frame 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.

  • include_row_labels (bool) – Indicates whether the security labels for each row should be egested along with the row. (since version 1.5.0)

Returns

Return type

list of lists

Raises
get_data_pandas(offset=0, length=None, include_row_labels=False, row_label_column_header=None)

Returns a Pandas DataFrame containing frame 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.

  • include_row_labels (bool) – Indicates whether the security labels for each row should be egested along with the row. (since version 1.5.0)

  • row_label_column_header (str) – The header column name to use for all row labels if include_row_labels is true and headers is true. (since version 1.5.0)

Returns

Return type

Pandas DataFrame

Raises
insert(data, row_labels=None, row_label_columns=None)

Inserts data rows. The properties of the new data must match the schema in both order and type.

Parameters

  • data (list or Pandas dataframe) – Data represented by a list of lists of data items or by a Pandas Dataframe.

  • row_labels (list) – A list of security labels to attach to each row inserted. Each label must have been passed in to the row_label_universe parameter when creating the frame. Note: Only one of row_labels and row_label_columns must be passed. (since version 1.5.0)

  • row_label_columns (list) – A list of integer column indices indicating which columns in the input data contain security labels to attach to the inserted row. Note: Only one of row_labels and row_label_columns must be passed. (since version 1.5.0)

Returns

A Job object representing the job that has executed the insert.

Return type

Job

Raises

  • XgtIOError – If there are errors in the data being inserted or some data could not be inserted into the frame.

  • XgtNameError – If the frame does not exist on the server.

  • XgtSecurityError – If the user does not have required permissions for this action.

  • XgtTransactionError – If a conflict with another transaction occurs.

load(paths, headerMode='none', record_history=True, row_labels=None, row_label_columns=None, delimiter=',')

Loads data from one or more CSV files specified in the list of paths. Each path may have its own protocol as described below.

Parameters

  • paths (list or string) –

    A single path or a list of paths to CSV files.

    Syntax for one CSV file path

    Resource type

    Path syntax

    local to Python:

    ’<path to csv file>’ ‘xgt://<path to csv file>’

    xGT server:

    ’xgtd://<path to csv file>’

    AWS s3:

    ’s3://<path to csv file>’

    https site:

    ’https://<path to csv file>’

    http site:

    ’http://<path to csv file>’

    ftps server:

    ’ftps://<path to csv file>’

    ftp server:

    ’ftp://<path to csv file>’

  • headerMode (str) –

    Indicates how the file header should be processed:

    • HeaderMode.NONE: No header exists.

    • HeaderMode.IGNORE: Ignore the first line containing the header.

    • HeaderMode.NORMAL: Process the header in non-strict mode. If a schema column is missing, a null value is ingested for that schema column. Any file column whose name does not correspond to a schema column or a security label column is ignored.

    • HeaderMode.STRICT: Process the header in strict mode. The name of each header column should correspond to a schema column, a security label column, or be named IGNORE. Each schema column must appear in the file.

    Optional. Default=HeaderMode.NONE.

  • record_history (bool) – If true, records the history of the job. (since version 1.4.0)

  • row_labels (list) – A list of security labels to attach to each row inserted with the load. Each label must have been passed in to the row_label_universe parameter when creating the frame. Note: Only one of row_labels and row_label_columns must be passed. (since version 1.5.0)

  • row_label_columns (list) – A list of columns indicating which columns in the CSV file contain security labels to attach to the inserted row. If the header mode is NONE or IGNORE, this must be a list of integer column indices. If the header mode is NORMAL or STRICT, this must be a list of string column names. Note: Only one of row_labels and row_label_columns must be passed. (since version 1.5.0)

  • delimiter (str) – Delimiter for data. (since version 1.5.1)

Returns

A Job object representing the job that has executed the load.

Return type

Job

Raises

  • XgtIOError – If a file specified cannot be opened or if there are errors inserting any lines in the file into the frame.

  • XgtNameError – If the frame does not exist on the server.

  • XgtSecurityError – If the user does not have required permissions for this action.

  • XgtTransactionError – If a conflict with another transaction occurs.

property name

Name of the frame.

Type

str

property num_rows

Gets the number of rows in the frame.

Type

int

property row_label_universe

Gets the universe of row security labels that can be attached to rows of this frame. Only labels that are also in the authenticated user’s label set are returned.

Type

list of strings

save(path, offset=0, length=None, headers=False, record_history=True, include_row_labels=False, row_label_column_header=None, preserve_order=False)

Writes the rows from the frame to a CSV file in the path and the computer indicated by the path.

Parameters

  • path (str) –

    Path to the CSV file.

    Syntax for one CSV file path

    Resource type

    Path syntax

    local to Python:

    ’<path to csv file>’ ‘xgt://<path to csv file>’

    xGT server:

    ’xgtd://<path to csv file>’

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

  • length (int) – Maximum number of rows to be retrieved. Optional. Default=None.

  • headers (boolean) – Indicates if headers should be added. Optional. Default=False.

  • record_history (bool) – If true, records the history of the job. (since version 1.4.0)

  • include_row_labels (bool) – Indicates whether the security labels for each row should be egested along with the row. (since version 1.5.0)

  • row_label_column_header (str) – The header column name to use for all row labels if include_row_labels is true and headers is true. (since version 1.5.0)

  • preserve_order (boolean) – Indicates if the output should keep the order the frame is stored in. Optional. Default=False. (since version 1.5.1)

Returns

A Job object representing the job that has executed the save.

Return type

Job

Raises
property schema

Gets the property names and types of the frame.

Type

list of lists