Skip to content

Backend Base Classes

BaseBackend (ABC)

Base backend class.

All Ibis backends must subclass this class and implement all the required methods.

Attributes

current_database: str | None property readonly

Return the name of the current database.

Backends that don't support different databases will return None.

Returns

str | None Name of the current database.

db_identity: str cached property writable

Return the identity of the database.

Multiple connections to the same database will return the same value for db_identity.

The default implementation assumes connection parameters uniquely specify the database.

Returns

Hashable Database identity

tables cached property writable

An accessor for tables in the database.

Tables may be accessed by name using either index or attribute access:

Examples

con = ibis.sqlite.connect("example.db") people = con.tables['people'] # access via index people = con.tables.people # access via attribute

version: str property readonly

Return the version of the backend engine.

For database servers, return the server version.

For others such as SQLite and pandas return the version of the underlying library or application.

Returns

str The backend version

Methods

add_operation(self, operation)

Add a translation function to the backend for a specific operation.

Operations are defined in ibis.expr.operations, and a translation function receives the translator object and an expression as parameters, and returns a value depending on the backend. For example, in SQL backends, a NullLiteral operation could be translated to the string "NULL".

Examples

@ibis.sqlite.add_operation(ibis.expr.operations.NullLiteral) ... def _null_literal(translator, expression): ... return 'NULL'

compile(self, expr, params=None)

Compile an expression.

connect(self, *args, **kwargs)

Connect to the database.

Parameters

args Connection parameters kwargs Additional connection parameters

Notes

This returns a new backend instance with saved args and kwargs, calling reconnect is called before returning.

Returns

BaseBackend An instance of the backend

create_database(self, name, force=False)

Create a new database.

Not all backends implement this method.

Parameters

name Name of the new database. force If False, an exception is raised if the database already exists.

create_table(self, name, obj=None, schema=None, database=None)

Create a new table.

Not all backends implement this method.

Parameters

name Name of the new table. obj An Ibis table expression or pandas table that will be used to extract the schema and the data of the new table. If not provided, schema must be given. schema The schema for the new table. Only one of schema or obj can be provided. database Name of the database where the table will be created, if not the default.

create_view(self, name, expr, database=None)

Create a view.

Parameters

name Name for the new view. expr An Ibis table expression that will be used to extract the query of the view. database Name of the database where the view will be created, if not the default.

database(self, name=None)

Return a Database object for the name database.

DEPRECATED: database is deprecated; use equivalent methods in the backend

Parameters

name Name of the database to return the object for.

Returns

Database A database object for the specified database.

drop_table(self, name, database=None, force=False)

Drop a table.

Parameters

name Name of the table to drop. database Name of the database where the table exists, if not the default. force If False, an exception is raised if the table does not exist.

drop_view(self, name, database=None, force=False)

Drop a view.

Parameters

name Name of the view to drop. database Name of the database where the view exists, if not the default. force If False, an exception is raised if the view does not exist.

execute(self, expr)

Execute an expression.

exists_database(self, name)

Return whether a database name exists in the current connection.

DEPRECATED: exists_database is deprecated as of v2.0; use name in client.list_databases()

Parameters

name Database to check for existence

Returns

bool Whether name exists

exists_table(self, name, database=None)

Return whether a table name exists in the database.

DEPRECATED: exists_table is deprecated as of v2.0; use name in client.list_tables()

Parameters

name Table name database Database to check if given

Returns

bool Whether name is a table

has_operation(operation) classmethod

Return whether the backend implements support for operation.

Parameters

operation A class corresponding to an operation.

Returns

bool Whether the backend implements the operation.

Examples

import ibis import ibis.expr.operations as ops ibis.sqlite.has_operation(ops.ArrayIndex) False ibis.postgres.has_operation(ops.ArrayIndex) True

list_databases(self, like=None)

List existing databases in the current connection.

Parameters

like A pattern in Python's regex format to filter returned database names.

Returns

list[str] The database names that exist in the current connection, that match the like pattern if provided.

list_tables(self, like=None, database=None)

Return the list of table names in the current database.

For some backends, the tables may be files in a directory, or other equivalent entities in a SQL database.

Parameters

like : str, optional A pattern in Python's regex format. database : str, optional The database to list tables of, if not the current one.

Returns

list[str] The list of the table names that match the pattern like.

register_options() classmethod

Register custom backend options.

table(self, name, database=None)

Return a table expression from the database.

DEPRECATED: table is deprecated as of v2.0; change the current database before calling .table()

verify(self, expr, params=None)

Verify expr is an expression that can be compiled.

DEPRECATED: verify is deprecated as of v2.0; compile and capture TranslationError instead


Last update: March 1, 2022