db

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

connect

firebolt.db.connection.connect(database: str = None, username: Optional[str] = None, password: Optional[str] = None, access_token: Optional[str] = None, auth: 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.db.connection.Connection(*args: Any, **kwargs: Any)

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

Close connection and all underlying cursors.

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.db.cursor.Cursor(*args: Any, **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
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

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

fetchall() → List[List[Optional[Union[int, float, str, datetime, date, bool, list, Decimal]]]]

Fetch all remaining rows of a query result.

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.

fetchone() → Optional[List[Optional[Union[int, float, str, datetime, date, bool, list, Decimal]]]]

Fetch the next row of a query result set.

get_status(query_id: str) → QueryStatus

Get status of a server-side async query. Return the state of the query.

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.