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.
connect
- async firebolt.async_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', disable_cache: bool = False, url: str | None = None, additional_parameters: Dict[str, Any] = {}) Connection
Connection
Note
Do not use connection directly. Instead, use connect as shown above.
- class firebolt.async_db.connection.Connection(engine_url: str, database: str | None, client: AsyncClient, cursor_type: Type[Cursor], api_endpoint: str, init_parameters: Dict[str, Any] | None = None)
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
- async cancel_async_query(token: str) None
Cancel an async query.
- Parameters:
token – Async query token. Can be obtained from Cursor.async_query_token.
- client_class: type
- property closed: bool
True if connection is closed; False otherwise.
- commit() None
Does nothing since Firebolt doesn’t have transactions.
- database
- engine_url
- async get_async_query_info(token: str) List[AsyncQueryInfo]
Retrieve information about an asynchronous query using its token. This method fetches the status and details of an asynchronous query identified by the provided token. :param token: The token identifying the asynchronous query. :type token: str
- Returns:
A list of AsyncQueryInfo objects containing details about the asynchronous query.
- Return type:
List[AsyncQueryInfo]
- async is_async_query_running(token: str) bool
Check if an async query is still running.
- Parameters:
token – Async query token. Can be obtained from Cursor.async_query_token.
- Returns:
True if async query is still running, False otherwise
- Return type:
bool
- async is_async_query_successful(token: str) bool | None
Check if an async query has finished and was successful.
- Parameters:
token – Async query token. Can be obtained from Cursor.async_query_token.
- Returns:
- None if the query is still running, True if successful,
False otherwise
- Return type:
bool
- firebolt.async_db.connection.connect_core(auth: Auth, user_agent_header: str, database: str | None = None, connection_url: str | None = None) Connection
Connect to Firebolt Core.
- Parameters:
auth (Auth) – Authentication object (must be FireboltCore)
user_agent_header (str) – User agent header string
database (Optional[str]) – Name of the database to connect to (defaults to ‘firebolt’)
connection_url (Optional[str]) – URL in format protocol://host:port Protocol defaults to http, host defaults to localhost, port defaults to 3473.
- Returns:
A connection to Firebolt Core
- Return type:
- async firebolt.async_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
- async firebolt.async_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.async_db.cursor.Cursor(*args: Any, client: AsyncClient, 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
- async aclose() None
- connection
- engine_url
- execute(query: str, parameters: Sequence[int | float | str | datetime | date | bool | Decimal | Sequence | bytes] | None = None, skip_parsing: bool = False, timeout_seconds: float | None = None) 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
timeout_seconds (Optional[float]) – Query execution timeout in seconds
- Returns:
Query row count.
- Return type:
int
- abstract async execute_async(query: str, parameters: Sequence[int | float | str | datetime | date | bool | Decimal | Sequence | bytes] | None = None, skip_parsing: bool = False) int
Execute a database query without maintaining a connection.
- execute_stream(query: str, parameters: Sequence[int | float | str | datetime | date | bool | Decimal | Sequence | bytes] | None = None, skip_parsing: bool = False) None
Prepare and execute a database query, with streaming results.
- 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 (Optional[Sequence[ParameterType]]) – 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
- executemany(query: str, parameters_seq: Sequence[Sequence[int | float | str | datetime | date | bool | Decimal | Sequence | bytes]], timeout_seconds: float | None = None) 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.
timeout_seconds (Optional[float]) – Query execution timeout in seconds.
- Returns:
Query row count.
- Return type:
int
- fetchall() List[List[int | float | str | datetime | date | bool | list | Decimal | None | bytes]]
Fetch all remaining rows of a query result.
- fetchmany(size: int | None = None) List[List[int | float | str | datetime | date | bool | list | Decimal | None | bytes]]
Fetch the next set of rows of a query result; cursor.arraysize is default size.
- fetchone() List[int | float | str | datetime | date | bool | list | Decimal | None | bytes] | None
Fetch the next row of a query result set.
- nextset() bool
Skip to the next available set, discarding any remaining rows from the current set.
- Returns:
True if there is a next result set, False otherwise
- Return type:
bool
- parameters: Dict[str, str]
- class firebolt.async_db.cursor.CursorV1(*args: Any, client: AsyncClientV1, connection: Connection, **kwargs: Any)
Bases:
Cursor
- connection
- engine_url
- async execute_async(query: str, parameters: Sequence[int | float | str | datetime | date | bool | Decimal | Sequence | bytes] | None = None, skip_parsing: bool = False) int
Execute a database query without maintaining a connection.
- async execute_stream(query: str, parameters: Sequence[int | float | str | datetime | date | bool | Decimal | Sequence | bytes] | None = None, skip_parsing: bool = False) None
Prepare and execute a database query, with streaming results.
- 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 (Optional[Sequence[ParameterType]]) – 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
- parameters: Dict[str, str]
- class firebolt.async_db.cursor.CursorV2(*args: Any, client: AsyncClientV2, connection: Connection, **kwargs: Any)
Bases:
Cursor
- connection
- engine_url
- execute_async(query: str, parameters: Sequence[int | float | str | datetime | date | bool | Decimal | Sequence | bytes] | None = None, skip_parsing: bool = False) int
Execute a database query without maintating a connection.
- 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.
- Not supported:
- Multi-statement queries: multiple statements, provided in a single query
and separated by semicolon.
- SET statements: to provide additional query execution parameters, execute
SET param=value statement before it. Use execute method to set parameters.
- 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 queries while potentially improving performance
- Returns:
Always returns -1, as async execution does not return row count.
- Return type:
int
- parameters: Dict[str, str]