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.