Connection API

This is the module that handles an overwhelming majority of communication with the server.

class tgdb.connection.TGConnection

This connection object represents a single session with the database.

First, to acquire a TGConnection object, call the TGConnectionFactory’s class method createConnection with the appropriate parameters. Do not directly instantiate a TGConnection object.

Next, to connect to the database, simply call the TGConnection object’s connect method. To insert an entity into the database on the next commit, call insertEntity. To update an entity already in the database, call updateEntity. To delete an entity, call deleteEntity. When you are ready to commit all of the database changes, call commit. To query, call executeQuery.

graphMetadata: tgdb.model.TGGraphMetadata

Gets this session’s graph metadata instance. Not settable or deletable. Useful for inquries about what types (nodetypes, edgetypes, and attrdescs) that are already in the database (and therefore what you can use).

graphObjectFactory: tgdb.model.TGGraphObjectFactory

Gets this session’s graph object factory instance. Not settable or deletable. Useful for creating other entities.

abstract commit()

Commit any changes to the database.

abstract connect()

Connects to the database.

Does not support reconnect, will need to create a new connection object for that.

Tip: Use this in a try-finally block with disconnect to always cleanly sever the connection with the database regardless of any exceptions.

abstract property connectedUsername

Gets the connected user’s name.

abstract createQuery(query: str) → tgdb.query.TGQuery

Creates a query for the database.

Will be used in the future as a way to write compiled/parameterized queries.

abstract deleteEntity(entity: tgdb.model.TGEntity)

Updates an entity already in the database

Need to call commit before any changes are finalized.

Parameters

entity – The entity to delete from the database.

abstract disconnect()

Disconnects from the database.

Once called, another connection object needs to be created to connect to the database again.

Tip: Use this in a try-finally block with connect to always cleanly sever the connection with the database regardless of any exceptions.

abstract executeQuery(query: str, option: tgdb.query.TGQueryOption = <tgdb.query.TGQueryOption object>) → tgdb.query.TGResultSet

Executes a query that is not parameterized.

Parameters

  • query – The query to execute. Should be of a supported format like TGQL or Gremlin. If its of a TGQL format, please prepend with tgql:// and if it is of a Gremlin, then prepend with a gremlin://.

  • option – The options for this query.

Returns

The result of the query. Will handle any cursoring if necessary

abstract getEntity(key: tgdb.model.TGKey, option: tgdb.query.TGQueryOption = <tgdb.query.TGQueryOption object>) → tgdb.model.TGEntity

Get an entity from the database.

Parameters

  • key – Key representing the primary key and/or the attributes set on a unique index.

  • option – A list of query options to determine how to acquire the entity (default: tgdb.query.DefaultQueryOption)

Returns

the entity if one was found.

abstract property graphMetadata

Gets the graph’s metadata.

abstract property graphObjectFactory

Gets a factory object for creating new entities.

abstract insertEntity(entity: tgdb.model.TGEntity)

Inserts an entity into the database.

Newly created entities will not automatically be inserted into the database.

Need to call commit before any changes are finalized.

Parameters

entity – The entity to insert into the database.

abstract property linkState

Gets the link state.

abstract property outboxaddr

Gets outbox (server) address.

abstract refreshMetadata()

Refreshes this connection’s metadata.

abstract rollback()

Rolls back the database.

abstract startExport(props: Optional[tgdb.utils.TGProperties] = None) → tgdb.bulkio.TGBulkExport

Starts the bulk export process with the server.

Parameters

props – TGProperties for starting the export process.

Returns

Returns a bulk export instance that handles the remainder of the bulk export.

abstract startImport(loadopt: Union[str, tgdb.bulkio.TGLoadOptions] = <TGLoadOptions.Insert: 'insert'>, erroropt: Union[str, tgdb.bulkio.TGErrorOptions] = <TGErrorOptions.Stop: 'stop'>, dateformat: Union[str, tgdb.bulkio.TGDateFormat] = <TGDateFormat.YMD: 'YMD'>, props: Optional[tgdb.utils.TGProperties] = None) → tgdb.bulkio.TGBulkImport

Starts the bulk import process with the server.

Parameters

  • loadopt – Whether to only insert entities or update entities if that primary key already is in the database.

  • erroropt – Whether to fail or ignore errors.

  • dateformat – How to interpret dates.

  • props – TGProperties for starting the import process.

Returns

Returns a bulk import instance that handles the remainder of the bulk import.

abstract updateEntity(entity: tgdb.model.TGEntity)

Updates an entity already in the database

Need to call commit before any changes are finalized.

Parameters

entity – The entity to update in the database.

class tgdb.connection.TGConnectionFactory

Factory for creating the TGConnection instance.

classmethod createAdminConnection(url: str, username: str, password: str, dbName: str = None, env: Dict[str, str] = None)

Creates a single administrative connection object.

Parameters

  • url – The URL for the database to connect to. When running on localhost, it should look like tcp://localhost:8222 for an insecure connection.

  • username – The user’s name of the database to use to connect to the database.

  • password – The user’s password for the database server.

  • dbName – The database to connect to

  • env – The environment to set up the connection with, contains any additional properties.

Returns

The administrative connection object requested.

Return type

tgdb.admin.TGAdminConnection

classmethod createConnection(url: str, username: str, password: str, dbName: str = None, env: Dict[str, str] = None) → tgdb.connection.TGConnection

Creates a single connection object.

Parameters

  • dbName –

  • url – The URL for the database to connect to. When running on localhost, it should look like tcp://localhost:8222 for an insecure connection.

  • username – The user’s name of the database to use to connect to the database.

  • password – The user’s password for the database server.

  • env – The environment to set up the connection with, contains any additional properties.

Returns

The connection object requested.