Async db

The async_db package enables asynchronous API calls to a Firebolt database, allowing client-side processes to continue to run while waiting for API responses. For executing queries asynchronously server-side see Server-side asynchronous query execution.

connect

async firebolt.async_db.connection.connect(database: Optional[str] = None, username: Optional[str] = None, password: Optional[str] = None, access_token: Optional[str] = None, auth: Optional[Auth] = None, engine_name: Optional[str] = None, engine_url: Optional[str] = None, account_name: Optional[str] = None, api_endpoint: str = 'api.app.firebolt.io', use_token_cache: bool = True, additional_parameters: Dict[str, Any] = {}) → Connection

Connect to Firebolt database.

Parameters

database (str) – Name of the database to connect
username (Optional[str]) – User name to use for authentication (Deprecated)
password (Optional[str]) – Password to use for authentication (Deprecated)
access_token (Optional[str]) – Authentication token to use instead of credentials (Deprecated)
auth (Auth) –
engine_name (Optional[str]) – Name of the engine to connect to
engine_url (Optional[str]) – The engine endpoint to use
account_name (Optional[str]) – For customers with multiple accounts; if none, default is used
api_endpoint (str) – Firebolt API endpoint. Used for authentication
use_token_cache (bool) – Cached authentication token in filesystem Default: True
additional_parameters (Optional[Dict]) – Dictionary of less widely-used arguments for connection

Note

Providing both engine_name and engine_url will result in an error

Connection

Note

Do not use connection directly. Instead, use connect as shown above.

class firebolt.async_db.connection.Connection(engine_url: str, database: str, auth: Auth, api_endpoint: str = 'api.app.firebolt.io', additional_parameters: Dict[str, Any] = {})

Bases: BaseConnection

Firebolt asynchronous database connection class. Implements PEP 249.

Parameters

engine_url – Firebolt database engine REST API url
database – Firebolt database name
username – Firebolt account username
password – Firebolt account password
api_endpoint – Optional. Firebolt API endpoint used for authentication
connector_versions – Optional. Tuple of connector name and version, or a list of tuples of your connector stack. Useful for tracking custom connector usage.

Note

Firebolt does not support transactions, so commit and rollback methods are not implemented.

async aclose() → None: Close connection and all underlying cursors.

api_endpoint

client_class: type

property closed: bool: True if connection is closed; False otherwise.

commit() → None: Does nothing since Firebolt doesn’t have transactions.

cursor() → Cursor

cursor_class: alias of Cursor

database

engine_url

Cursor

class firebolt.async_db.cursor.Cursor(*args: Any, **kwargs: Any)

Bases: BaseCursor

Executes asyncio queries to Firebolt Database. Should not be created directly; use connection.cursor

Parameters

description – Information about a single result row.
rowcount – The number of rows produced by last query.
closed – True if connection is closed; False otherwise.
arraysize – Read/Write, specifies the number of rows to fetch at a time with the fetchmany() method.

connection

async execute(query: str, parameters: Optional[Sequence[Union[int, float, str, datetime, date, bool, Decimal, Sequence]]] = None, skip_parsing: bool = False, async_execution: Optional[bool] = False) → Union[int, str]

Prepare and execute a database query.

Supported features:

Parameterized queries: placeholder characters (‘?’) are substituted: with values provided in parameters. Values are formatted to be properly recognized by database and to exclude SQL injection.
Multi-statement queries: multiple statements, provided in a single query: and separated by semicolon, are executed separatelly and sequentially. To switch to next statement result, nextset method should be used.
SET statements: to provide additional query execution parameters, execute: SET param=value statement before it. All parameters are stored in cursor object until it’s closed. They can also be removed with flush_parameters method call.

Parameters

query (str) – SQL query to execute
parameters (Optional[Sequence[ParameterType]]) – A sequence of substitution parameters. Used to replace ‘?’ placeholders inside a query with actual values
skip_parsing (bool) – Flag to disable query parsing. This will disable parameterized, multi-statement and SET queries, while improving performance
async_execution (bool) – flag to determine if query should be asynchronous

Returns

Query row count.

Return type

int

async executemany(query: str, parameters_seq: Sequence[Sequence[Union[int, float, str, datetime, date, bool, Decimal, Sequence]]], async_execution: Optional[bool] = False) → Union[int, str]

Prepare and execute a database query.

Supports providing multiple substitution parameter sets, executing them as multiple statements sequentially.

Supported features:

Parameterized queries: Placeholder characters (‘?’) are substituted: with values provided in parameters. Values are formatted to be properly recognized by database and to exclude SQL injection.
Multi-statement queries: Multiple statements, provided in a single query: and separated by semicolon, are executed separately and sequentially. To switch to next statement result, use nextset method.
SET statements: To provide additional query execution parameters, execute: SET param=value statement before it. All parameters are stored in cursor object until it’s closed. They can also be removed with flush_parameters method call.

Parameters

query (str) – SQL query to execute.
parameters_seq (Sequence[Sequence[ParameterType]]) – A sequence of substitution parameter sets. Used to replace ‘?’ placeholders inside a query with actual values from each set in a sequence. Resulting queries for each subset are executed sequentially.
async_execution (bool) – flag to determine if query should be asynchronous

Returns

Query row count for synchronous execution of queries, query ID string for asynchronous execution.

Return type

int|str

async fetchall() → List[List[Optional[Union[int, float, str, datetime, date, bool, list, Decimal]]]]: Fetch all remaining rows of a query result.

async fetchmany(size: Optional[int] = None) → List[List[Optional[Union[int, float, str, datetime, date, bool, list, Decimal]]]]: Fetch the next set of rows of a query result; cursor.arraysize is default size.

async fetchone() → Optional[List[Optional[Union[int, float, str, datetime, date, bool, list, Decimal]]]]: Fetch the next row of a query result set.

async nextset() → Optional[bool]: Skip to the next available set, discarding any remaining rows from the current set. Returns True if operation was successful; None if there are no more sets to retrive.

class firebolt.async_db.cursor.CursorState(value)

Bases: Enum

An enumeration.

CLOSED = 4

DONE = 3

ERROR = 2

NONE = 1

class firebolt.async_db.cursor.QueryStatus(value)

Bases: Enum

Enumeration of query responses on server-side async queries.

CANCELED_EXECUTION = 7

ENDED_SUCCESSFULLY = 2

ENDED_UNSUCCESSFULLY = 3

EXECUTION_ERROR = 8

NOT_READY = 4

PARSE_ERROR = 6

RUNNING = 1

STARTED_EXECUTION = 5

class firebolt.async_db.cursor.Statistics(*, elapsed: float, rows_read: int, bytes_read: int, time_before_execution: float, time_to_execute: float, scanned_bytes_cache: float = None, scanned_bytes_storage: float = None)

Bases: BaseModel

Class for query execution statistics.

bytes_read: int

elapsed: float

rows_read: int

scanned_bytes_cache: Optional[float]

scanned_bytes_storage: Optional[float]

time_before_execution: float

time_to_execute: float

Util

async firebolt.async_db.util.is_db_available(connection: Connection, database_name: str) → bool

Verify that the database exists.

Parameters: connection (firebolt.async_db.connection.Connection) –

async firebolt.async_db.util.is_engine_running(connection: Connection, engine_url: str) → bool

Verify that the engine is running.

Parameters: connection (firebolt.async_db.connection.Connection) – connection.