API Reference

phoenixdb module

phoenixdb.connect(url, max_retries=None, **kwargs)

Connects to a Phoenix query server.

Parameters:
  • url – URL to the Phoenix query server, e.g. http://localhost:8765/
  • autocommit – Switch the connection to autocommit mode.
  • readonly – Switch the connection to readonly mode.
  • max_retries – The maximum number of retries in case there is a connection error.
Returns:

Connection object.

phoenixdb.Date(year, month, day)

Constructs an object holding a date value.

phoenixdb.Time(hour, minute, second)

Constructs an object holding a time value.

phoenixdb.Timestamp(year, month, day, hour, minute, second)

Constructs an object holding a datetime/timestamp value.

phoenixdb.DateFromTicks(ticks)

Constructs an object holding a date value from the given UNIX timestamp.

phoenixdb.TimeFromTicks(ticks)

Constructs an object holding a time value from the given UNIX timestamp.

phoenixdb.TimestampFromTicks(ticks)

Constructs an object holding a datetime/timestamp value from the given UNIX timestamp.

phoenixdb.Binary(value)

Constructs an object capable of holding a binary (long) string value.

class phoenixdb.TypeHelper
static from_class(klass)

Retrieves a Rep and functions to cast to/from based on the Java class.

Parameters:klass – The string of the Java class for the column or parameter.
Returns:tuple (field_name, rep, mutate_to, cast_from) WHERE field_name is the attribute in common_pb2.TypedValue rep is the common_pb2.Rep enum mutate_to is the function to cast values into Phoenix values, if any cast_from is the function to cast from the Phoenix value to the Python value, if any
Raises:NotImplementedError
exception phoenixdb.Warning

Not used by this package, only defined for compatibility with DB API 2.0.

exception phoenixdb.Error(message, code=None, sqlstate=None, cause=None)

Exception that is the base class of all other error exceptions. You can use this to catch all errors with one single except statement.

cause
code
message
sqlstate
exception phoenixdb.InterfaceError(message, code=None, sqlstate=None, cause=None)

Exception raised for errors that are related to the database interface rather than the database itself.

exception phoenixdb.DatabaseError(message, code=None, sqlstate=None, cause=None)

Exception raised for errors that are related to the database.

exception phoenixdb.DataError(message, code=None, sqlstate=None, cause=None)

Exception raised for errors that are due to problems with the processed data like division by zero, numeric value out of range, etc.

exception phoenixdb.OperationalError(message, code=None, sqlstate=None, cause=None)

Raised for errors that are related to the database’s operation and not necessarily under the control of the programmer, e.g. an unexpected disconnect occurs, the data source name is not found, a transaction could not be processed, a memory allocation error occurred during processing, etc.

exception phoenixdb.IntegrityError(message, code=None, sqlstate=None, cause=None)

Raised when the relational integrity of the database is affected, e.g. a foreign key check fails.

exception phoenixdb.InternalError(message, code=None, sqlstate=None, cause=None)

Raised when the database encounters an internal problem.

exception phoenixdb.ProgrammingError(message, code=None, sqlstate=None, cause=None)

Raises for programming errors, e.g. table not found, syntax error, etc.

exception phoenixdb.NotSupportedError(message, code=None, sqlstate=None, cause=None)

Raised when using an API that is not supported by the database.

phoenixdb.connection module

class phoenixdb.connection.Connection(client, **kwargs)

Database connection.

You should not construct this object manually, use connect() instead.

exception DataError(message, code=None, sqlstate=None, cause=None)

Exception raised for errors that are due to problems with the processed data like division by zero, numeric value out of range, etc.

exception Connection.DatabaseError(message, code=None, sqlstate=None, cause=None)

Exception raised for errors that are related to the database.

exception Connection.Error(message, code=None, sqlstate=None, cause=None)

Exception that is the base class of all other error exceptions. You can use this to catch all errors with one single except statement.

cause
code
message
sqlstate
exception Connection.IntegrityError(message, code=None, sqlstate=None, cause=None)

Raised when the relational integrity of the database is affected, e.g. a foreign key check fails.

exception Connection.InterfaceError(message, code=None, sqlstate=None, cause=None)

Exception raised for errors that are related to the database interface rather than the database itself.

exception Connection.InternalError(message, code=None, sqlstate=None, cause=None)

Raised when the database encounters an internal problem.

exception Connection.NotSupportedError(message, code=None, sqlstate=None, cause=None)

Raised when using an API that is not supported by the database.

exception Connection.OperationalError(message, code=None, sqlstate=None, cause=None)

Raised for errors that are related to the database’s operation and not necessarily under the control of the programmer, e.g. an unexpected disconnect occurs, the data source name is not found, a transaction could not be processed, a memory allocation error occurred during processing, etc.

exception Connection.ProgrammingError(message, code=None, sqlstate=None, cause=None)

Raises for programming errors, e.g. table not found, syntax error, etc.

exception Connection.Warning

Not used by this package, only defined for compatibility with DB API 2.0.

Connection.autocommit

Read/write attribute for switching the connection’s autocommit mode.

Connection.close()

Closes the connection. No further operations are allowed, either on the connection or any of its cursors, once the connection is closed.

If the connection is used in a with statement, this method will be automatically called at the end of the with block.

Connection.closed

Read-only attribute specifying if the connection is closed or not.

Connection.commit()

Commits pending database changes.

Currently, this does nothing, because the RPC does not support transactions. Only defined for DB API 2.0 compatibility. You need to use autocommit mode.

Connection.cursor()

Creates a new cursor.

Returns:A Cursor object.
Connection.open()

Opens the connection.

Connection.readonly

Read/write attribute for switching the connection’s readonly mode.

Connection.set_session(autocommit=None, readonly=None)

Sets one or more parameters in the current connection.

Parameters:
  • autocommit – Switch the connection to autocommit mode. With the current version, you need to always enable this, because commit() is not implemented.
  • readonly – Switch the connection to read-only mode.
Connection.transactionisolation

Read/write attribute for switching the connection’s readonly mode.

phoenixdb.cursor module

class phoenixdb.cursor.Cursor(connection, id=None)

Database cursor for executing queries and iterating over results.

You should not construct this object manually, use Connection.cursor() instead.

arraysize = 1
close()

Closes the cursor. No further operations are allowed once the cursor is closed.

If the cursor is used in a with statement, this method will be automatically called at the end of the with block.

closed

Read-only attribute specifying if the cursor is closed or not.

connection

Read-only attribute providing access to the Connection object this cursor was created from.

description
execute(operation, parameters=None)
executemany(operation, seq_of_parameters)
fetchall()
fetchmany(size=None)
fetchone()
itersize = 2000
next()
rowcount

Read-only attribute specifying the number of rows affected by the last executed DML statement or -1 if the number cannot be determined. Note that this will always be set to -1 for select queries.

rownumber

Read-only attribute providing the current 0-based index of the cursor in the result set or None if the index cannot be determined.

The index can be seen as index of the cursor in a sequence (the result set). The next fetch operation will fetch the row indexed by rownumber in that sequence.

setinputsizes(sizes)
setoutputsize(size, column=None)
class phoenixdb.cursor.ColumnDescription(name, type_code, display_size, internal_size, precision, scale, null_ok)
display_size

Alias for field number 2

internal_size

Alias for field number 3

name

Alias for field number 0

null_ok

Alias for field number 6

precision

Alias for field number 4

scale

Alias for field number 5

type_code

Alias for field number 1

phoenixdb.avatica module

Implementation of the JSON-over-HTTP RPC protocol used by Avatica.

class phoenixdb.avatica.AvaticaClient(url, max_retries=None)

Client for Avatica’s RPC server.

This exposes all low-level functionality that the Avatica server provides, using the native terminology. You most likely do not want to use this class directly, but rather get connect to a server using phoenixdb.connect().

close()

Closes the HTTP connection to the RPC server.

close_connection(connection_id)

Closes a connection.

Parameters:connection_id – ID of the connection to close.
close_statement(connection_id, statement_id)

Closes a statement.

Parameters:
  • connection_id – ID of the current connection.
  • statement_id – ID of the statement to close.
connect()

Opens a HTTP connection to the RPC server.

connection_sync(connection_id, connProps=None)

Synchronizes connection properties with the server.

Parameters:
  • connection_id – ID of the current connection.
  • connProps – Dictionary with the properties that should be changed.
Returns:

A common_pb2.ConnectionProperties object.

create_statement(connection_id)

Creates a new statement.

Parameters:connection_id – ID of the current connection.
Returns:New statement ID.
execute(connection_id, statement_id, signature, parameter_values=None, first_frame_max_size=None)

Returns a frame of rows.

The frame describes whether there may be another frame. If there is not another frame, the current iteration is done when we have finished the rows in the this frame.

Parameters:
  • connection_id – ID of the current connection.
  • statement_id – ID of the statement to fetch rows from.
  • signature – common_pb2.Signature object
  • parameter_values – A list of parameter values, if statement is to be executed; otherwise None.
  • first_frame_max_size – The maximum number of rows that will be returned in the first Frame returned for this query.
Returns:

Frame data, or None if there are no more.

fetch(connection_id, statement_id, offset=0, frame_max_size=None)

Returns a frame of rows.

The frame describes whether there may be another frame. If there is not another frame, the current iteration is done when we have finished the rows in the this frame.

Parameters:
  • connection_id – ID of the current connection.
  • statement_id – ID of the statement to fetch rows from.
  • offset – Zero-based offset of first row in the requested frame.
  • frame_max_size – Maximum number of rows to return; negative means no limit.
Returns:

Frame data, or None if there are no more.

get_catalogs(connection_id)
get_columns(connection_id, catalog=None, schemaPattern=None, tableNamePattern=None, columnNamePattern=None)
get_schemas(connection_id, catalog=None, schemaPattern=None)
get_table_types(connection_id)
get_tables(connection_id, catalog=None, schemaPattern=None, tableNamePattern=None, typeList=None)
get_type_info(connection_id)
open_connection(connection_id, info=None)

Opens a new connection.

Parameters:connection_id – ID of the connection to open.
prepare(connection_id, sql, max_rows_total=None)

Prepares a statement.

Parameters:
  • connection_id – ID of the current connection.
  • sql – SQL query.
  • max_rows_total – The maximum number of rows that will be allowed for this query.
Returns:

Signature of the prepared statement.

prepare_and_execute(connection_id, statement_id, sql, max_rows_total=None, first_frame_max_size=None)

Prepares and immediately executes a statement.

Parameters:
  • connection_id – ID of the current connection.
  • statement_id – ID of the statement to prepare.
  • sql – SQL query.
  • max_rows_total – The maximum number of rows that will be allowed for this query.
  • first_frame_max_size – The maximum number of rows that will be returned in the first Frame returned for this query.
Returns:

Result set with the signature of the prepared statement and the first frame data.