docs: improve docstrings on methods using the database param

Author: NickCrews

docs/backend_table_hierarchy.qmd docs/concepts/backend-table-hierarchy.qmddocs/backend_table_hierarchy.qmd renamed to docs/concepts/backend-table-hierarchy.qmd

@@ -2,15 +2,18 @@
 title: Backend Table Hierarchy
 ---
 
-Several SQL backends support two levels of hierarchy in organizing tables
-(although the levels are also used for other purposes, like data access,
-billing, etc.).
+Most SQL backends organize tables into groups, and some use a two-level hierarchy.
+They use terms such as `catalog`, `database`, and/or `schema` to refer to these groups.
 
-Ibis uses the following terminology:
+Ibis uses the following terminology throughout its codebase, API, and documentation:
 
 - `database`: a collection of tables
 - `catalog`: a collection of databases
 
+In other words, the full specification of a table in Ibis is either
+- `catalog.database.table`
+- `database.table`
+
 Below is a table with the terminology used by each backend for the two levels of
 hierarchy. This is provided as a reference, note that when using Ibis, we will
 use the terms `catalog` and `database` and map them onto the appropriate fields.
@@ -31,7 +34,8 @@ use the terms `catalog` and `database` and map them onto the appropriate fields.
 | pandas     |                | NA         |
 | polars     |                | NA         |
 | postgres   | database       | schema     |
-| pyspark    |                | database   |
+| pyspark    | database       | schema     |
 | risingwave | database       | schema     |
-| snowflake  |                | database   |
+| sqlite     |                | schema     |
+| snowflake  | database       | schema     |
 | trino      | catalog        | schema     |

ibis/backends/__init__.py

@@ -617,6 +617,52 @@ def to_json(
         )
 
 
+class HasCurrentCatalog(abc.ABC):
+    @property
+    @abc.abstractmethod
+    def current_catalog(self) -> str:
+        """The name of the current catalog in the backend.
+
+        A collection of `table` is referred to as a `database`.
+        A collection of `database` is referred to as a `catalog`.
+
+        These terms are mapped onto the corresponding features in each
+        backend (where available), regardless of the terminology the backend uses.
+
+        See the
+        [Table Hierarchy Concepts Guide](/concepts/backend-table-hierarchy.qmd)
+        for more info.
+
+        Returns
+        -------
+        str
+            The name of the current catalog.
+        """
+
+
+class HasCurrentDatabase(abc.ABC):
+    @property
+    @abc.abstractmethod
+    def current_database(self) -> str:
+        """The name of the current database in the backend.
+
+        A collection of `table` is referred to as a `database`.
+        A collection of `database` is referred to as a `catalog`.
+
+        These terms are mapped onto the corresponding features in each
+        backend (where available), regardless of the terminology the backend uses.
+
+        See the
+        [Table Hierarchy Concepts Guide](/concepts/backend-table-hierarchy.qmd)
+        for more info.
+
+        Returns
+        -------
+        str
+            The name of the current database.
+        """
+
+
 class CanListCatalog(abc.ABC):
     @abc.abstractmethod
     def list_catalogs(self, *, like: str | None = None) -> list[str]:
@@ -629,15 +675,17 @@ def list_catalogs(self, *, like: str | None = None) -> list[str]:
         A collection of `database` is referred to as a `catalog`.
 
         These terms are mapped onto the corresponding features in each
-        backend (where available), regardless of whether the backend itself
-        uses the same terminology.
+        backend (where available), regardless of the terminology the backend uses.
+
+        See the
+        [Table Hierarchy Concepts Guide](/concepts/backend-table-hierarchy.qmd)
+        for more info.
         :::
 
         Parameters
         ----------
         like
-            A pattern in Python's regex format to filter returned database
-            names.
+            A pattern in Python's regex format to filter returned catalog names.
 
         Returns
         -------
@@ -659,8 +707,11 @@ def create_catalog(self, name: str, /, *, force: bool = False) -> None:
         A collection of `database` is referred to as a `catalog`.
 
         These terms are mapped onto the corresponding features in each
-        backend (where available), regardless of whether the backend itself
-        uses the same terminology.
+        backend (where available), regardless of the terminology the backend uses.
+
+        See the
+        [Table Hierarchy Concepts Guide](/concepts/backend-table-hierarchy.qmd)
+        for more info.
         :::
 
         Parameters
@@ -682,8 +733,11 @@ def drop_catalog(self, name: str, /, *, force: bool = False) -> None:
         A collection of `database` is referred to as a `catalog`.
 
         These terms are mapped onto the corresponding features in each
-        backend (where available), regardless of whether the backend itself
-        uses the same terminology.
+        backend (where available), regardless of the terminology the backend uses.
+
+        See the
+        [Table Hierarchy Concepts Guide](/concepts/backend-table-hierarchy.qmd)
+        for more info.
         :::
 
         Parameters
@@ -709,8 +763,11 @@ def list_databases(
         A collection of `database` is referred to as a `catalog`.
 
         These terms are mapped onto the corresponding features in each
-        backend (where available), regardless of whether the backend itself
-        uses the same terminology.
+        backend (where available), regardless of the terminology the backend uses.
+
+        See the
+        [Table Hierarchy Concepts Guide](/concepts/backend-table-hierarchy.qmd)
+        for more info.
         :::
 
         Parameters
@@ -737,6 +794,20 @@ def create_database(
     ) -> None:
         """Create a database named `name` in `catalog`.
 
+        ::: {.callout-note}
+        ## Ibis does not use the word `schema` to refer to database hierarchy.
+
+        A collection of `table` is referred to as a `database`.
+        A collection of `database` is referred to as a `catalog`.
+
+        These terms are mapped onto the corresponding features in each
+        backend (where available), regardless of the terminology the backend uses.
+
+        See the
+        [Table Hierarchy Concepts Guide](/concepts/backend-table-hierarchy.qmd)
+        for more info.
+        :::
+
         Parameters
         ----------
         name
@@ -755,13 +826,27 @@ def drop_database(
     ) -> None:
         """Drop the database with `name` in `catalog`.
 
+        ::: {.callout-note}
+        ## Ibis does not use the word `schema` to refer to database hierarchy.
+
+        A collection of `table` is referred to as a `database`.
+        A collection of `database` is referred to as a `catalog`.
+
+        These terms are mapped onto the corresponding features in each
+        backend (where available), regardless of the terminology the backend uses.
+
+        See the
+        [Table Hierarchy Concepts Guide](/concepts/backend-table-hierarchy.qmd)
+        for more info.
+        :::
+
         Parameters
         ----------
         name
             Name of the schema to drop.
         catalog
-            Name of the catalog to drop the database from. If `None`, the
-            current catalog is used.
+            Name of the catalog to drop the database from.
+            If `None`, the current catalog is used.
         force
             If `False`, an exception is raised if the database does not exist.
 
@@ -981,73 +1066,105 @@ def _filter_with_like(values: Iterable[str], like: str | None = None) -> list[st
     def list_tables(
         self, *, like: str | None = None, database: tuple[str, str] | str | None = None
     ) -> list[str]:
-        """Return the list of table names in the current database.
+        """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.
 
-        ::: {.callout-note}
-        ## Ibis does not use the word `schema` to refer to database hierarchy.
-
-        A collection of tables is referred to as a `database`.
-        A collection of `database` is referred to as a `catalog`.
-
-        These terms are mapped onto the corresponding features in each
-        backend (where available), regardless of whether the backend itself
-        uses the same terminology.
-        :::
-
         Parameters
         ----------
         like
             A pattern in Python's regex format.
         database
-            The database from which to list tables.
-            If not provided, the current database is used.
+            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
+        --------
+        >>> 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)")  # doctest: +ELLIPSIS
+        <duckdb.duckdb.DuckDBPyConnection object at 0x...>
+        >>> con.list_tables(database="my_database")
+        ['baz']
         """
 
     @abc.abstractmethod
     def table(
         self, name: str, /, *, database: tuple[str, str] | str | None = None
     ) -> ir.Table:
-        """Construct a table expression.
-
-        ::: {.callout-note}
-        ## Ibis does not use the word `schema` to refer to database hierarchy.
-
-        A collection of tables is referred to as a `database`.
-        A collection of `database` is referred to as a `catalog`.
-
-        These terms are mapped onto the corresponding features in each
-        backend (where available), regardless of whether the backend itself
-        uses the same terminology.
-        :::
+        """Construct a table expression from the corresponding table in the backend.
 
         Parameters
         ----------
         name
             Table name
         database
-            Database name
-            If not provided, the current database is used.
+            The database, or (catalog, database) from which to get the table.
+
+            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
         -------
         Table
             Table expression
 
+        Examples
+        --------
+        >>> import ibis
+        >>> backend = ibis.duckdb.connect()
+
+        Get the "foo" table from the current database
+        (and catalog, if applicable for this backend):
+
+        >>> backend.table("foo")  # doctest: +SKIP
+
+        Get the "foo" table from the "bar" database
+        (in DuckDB's language they would say the "bar" schema,
+        in SQL this would be `"bar"."foo"`)
+
+        >>> backend.table("foo", database="bar")  # doctest: +SKIP
+
+        Get the "foo" table from the "bar" database, within the "baz" catalog
+        (in DuckDB's language they would say the "bar" schema, and "baz" database,
+        in SQL this would be `"baz"."bar"."foo"`)
+
+        >>> backend.table("foo", database=("baz", "bar"))  # doctest: +SKIP
         """
 
     @property