db

The DB package enables connecting to a Firebolt database for synchronous queries.

connect

firebolt.db.connection.connect(auth: Auth | None = None, account_name: str | None = None, database: str | None = None, engine_name: str | None = None, engine_url: str | None = None, api_endpoint: str = 'api.app.firebolt.io', additional_parameters: Dict[str, Any] = {}) → Connection

Connection

Note

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

class firebolt.db.connection.Connection(engine_url: str, database: str | None, client: Client, cursor_type: Type[Cursor], system_engine_connection: Connection | None, api_endpoint: str = 'api.app.firebolt.io')

Bases: BaseConnection

Firebolt 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.

Note

Firebolt currenly doesn’t support transactions so commit and rollback methods are not implemented.

api_endpoint

client_class: type

close() → None

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

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

cursor(**kwargs: Any) → Cursor

cursor_type: Type[Cursor]

database

engine_url

firebolt.db.connection.connect(auth: Auth | None = None, account_name: str | None = None, database: str | None = None, engine_name: str | None = None, engine_url: str | None = None, api_endpoint: str = 'api.app.firebolt.io', additional_parameters: Dict[str, Any] = {}) → Connection

firebolt.db.connection.connect_v1(auth: Auth, user_agent_header: str, database: str | None = None, account_name: str | None = None, engine_name: str | None = None, engine_url: str | None = None, api_endpoint: str = 'api.app.firebolt.io') → Connection

firebolt.db.connection.connect_v2(auth: Auth, user_agent_header: str, account_name: str | None = None, database: str | None = None, engine_name: str | None = None, api_endpoint: str = 'api.app.firebolt.io') → Connection

Connect to Firebolt.

Parameters:

auth (Auth) –
database (str) – Name of the database to connect
engine_name (Optional[str]) – Name of the engine to connect to
account_name (Optional[str]) – For customers with multiple accounts; if none, default is used
api_endpoint (str) – Firebolt API endpoint. Used for authentication
additional_parameters (Optional[Dict]) – Dictionary of less widely-used arguments for connection

Cursor

class firebolt.db.cursor.Cursor(*args: Any, client: Client, connection: Connection, **kwargs: Any)

Bases: BaseCursor

Class, responsible for executing 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

cancel(query_id: str) → None: Cancel a server-side async query.

connection

property database: str | None

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

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

get_status(query_id: str) → QueryStatus: Get status of a server-side async query. Return the state of the query.

parameters: Dict[str, str]

class firebolt.db.cursor.CursorV1(*args: Any, client: ClientV1, connection: Connection, **kwargs: Any)

Bases: Cursor

connection

parameters: Dict[str, str]

class firebolt.db.cursor.CursorV2(*args: Any, client: Client, connection: Connection, **kwargs: Any)

Bases: Cursor

connection

parameters: Dict[str, str]