Backend#

class nominal.ibis.Backend(*args, **kwargs)#

Bases: SQLBackend, NoUrl

Ibis backend executing queries against the Nominal SQL API.

compiler = <nominal.ibis._backend.NominalCompiler object>#

name = 'nominal'#

supports_python_udfs = False#

supports_temporary_tables = False#

property version: str#

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

workspace_rid: str#

create_table(*args: Any, **kwargs: Any) → Table#

Create a new table.

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.
temp: Whether a table is temporary or not
overwrite: Whether to clobber existing data

Returns#

Table: The table that was created.

create_view(*args: Any, **kwargs: Any) → Table#

Create a view from an Ibis expression.

Parameters#

name: The name of the view to create.
obj: The Ibis expression to create the view from.
database: The database that the view should be created in.
overwrite: If True, replace an existing view with the same name.

Returns#

ir.Table: A table expression representing the view.

disconnect() → None#: No-op: the gRPC channel belongs to the NominalClient.

do_connect(client: NominalClient) → None#

Use an existing client and fetch the SQL catalog.

Parameters:: client – Authenticated Nominal client. Queries run in its default workspace, either the one pinned in the profile or the tenant default.

drop_table(*args: Any, **kwargs: Any) → None#

Drop a table from the backend.

Parameters#

name: The name of the table to drop
database: The database that the table is located in.
force: If True, do not raise an error if the table does not exist.

drop_view(*args: Any, **kwargs: Any) → None#

Drop a view from the backend.

Parameters#

name: The name of the view to drop.
database: The database that the view is located in.
force: If True, do not raise an error if the view does not exist.

execute(expr: Expr, /, *, params: Mapping[Scalar, Any] | None = None, limit: int | str | None = None, **kwargs: Any) → Any#

Execute an Ibis expression and return a pandas DataFrame, Series, or scalar.

Parameters#

expr: Ibis expression to execute.
params: Mapping of scalar parameter expressions to value.
limit: An integer to effect a specific row limit. A value of None means no limit. The default is in ibis/config.py.
kwargs: Keyword arguments

Returns#

DataFrame | Series | scalar: The result of the expression execution.

get_schema(table_name: str, *, catalog: str | None = None, database: str | None = None) → Schema#

list_tables(*, like: str | None = None, database: tuple[str, str] | str | None = None) → list[str]#

The table names that match like in the given database.

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

Parameters#

like

A pattern in Python’s regex format.

database

The database, or (catalog, database) from which to list tables.

For backends that support a single-level table hierarchy, you can pass in a string like "bar". For backends that support multi-level table hierarchies, you can pass in a dotted string path like "catalog.database" or a tuple of strings like ("catalog", "database"). If not provided, the current database (and catalog, if applicable for this backend) is used.

See the [Table Hierarchy Concepts Guide](/concepts/backend-table-hierarchy.qmd) for more info.

Returns#

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

Examples#

This example uses the DuckDB backend, but the list_tables API works the same for other backends.

>>> import ibis
>>> con = ibis.duckdb.connect()
>>> foo = con.create_table("foo", schema=ibis.schema(dict(a="int")))
>>> con.list_tables()
['foo']
>>> bar = con.create_view("bar", foo)
>>> con.list_tables()
['bar', 'foo']
>>> con.create_database("my_database")
>>> con.list_tables(database="my_database")
[]
>>> con.raw_sql("CREATE TABLE my_database.baz (a INTEGER)")
<duckdb.duckdb.DuckDBPyConnection object at 0x...>
>>> con.list_tables(database="my_database")
['baz']

raw_sql(query: str) → Table#

to_pyarrow(expr: Expr, /, *, params: Mapping[Scalar, Any] | None = None, limit: int | str | None = None, **kwargs: Any) → Any#: Execute the expression and return its result as a PyArrow Table, ChunkedArray, or Scalar.

to_pyarrow_batches(expr: Expr, /, *, params: Mapping[Scalar, Any] | None = None, limit: int | str | None = None, chunk_size: int = 1_000_000, **kwargs: Any) → RecordBatchReader#

Execute the expression, streaming record batches without materializing the result.

Closing the reader releases the active query stream. Errors encountered while reading batches are reported as PyArrow exceptions.