docs: improve docstrings on methods using the database param

Author: NickCrews

docs/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.
@@ -33,5 +36,6 @@ use the terms `catalog` and `database` and map them onto the appropriate fields.
 | postgres   | database       | schema     |
 | pyspark    |                | database   |
 | risingwave | database       | schema     |
+| sqlite     |                | schema     |
 | snowflake  |                | database   |
 | trino      | catalog        | schema     |

ibis/backends/__init__.py

@@ -629,15 +629,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 +661,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 +687,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 +717,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 +748,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 +780,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 +1020,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

ibis/backends/athena/__init__.py

@@ -210,20 +210,6 @@ def create_table(
         return self.table(orig_table_ref.name, database=(catalog, db))
 
     def table(self, name: str, /, *, database: str | None = None) -> ir.Table:
-        """Construct a table expression.
-
-        Parameters
-        ----------
-        name
-            Table name
-        database
-            Database name
-
-        Returns
-        -------
-        Table
-            Table expression
-        """
         table_loc = self._to_sqlglot_table(database)
 
         # TODO: set these to better defaults
@@ -311,20 +297,6 @@ def list_catalogs(self, *, like: str | None = None) -> list[str]:
     def list_databases(
         self, like: str | None = None, catalog: str | None = None
     ) -> list[str]:
-        """List databases.
-
-        Parameters
-        ----------
-        like
-            Regular expression to use to match database names.
-        catalog
-            Catalog in which to search for databases.
-
-        Returns
-        -------
-        list[str]
-            A list of databases in `catalog` matching the pattern `like`.
-        """
         if catalog is None:
             catalog = self.current_catalog
         with self.con.cursor() as cur:
@@ -483,57 +455,6 @@ def drop_database(
     def list_tables(
         self, *, like: str | None = None, database: tuple[str, str] | str | None = None
     ) -> list[str]:
-        """List tables and views.
-
-        ::: {.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
-            Regex to filter by table/view name.
-        database
-            Database location. If not passed, uses the current database.
-
-            By default uses the current `database` (`self.current_database`) and
-            `catalog` (`self.current_catalog`).
-
-            To specify a table in a separate catalog, you can pass in the
-            catalog and database as a string `"catalog.database"`, or as a tuple of
-            strings `("catalog", "database")`.
-
-        Returns
-        -------
-        list[str]
-            List of table and view names.
-
-        Examples
-        --------
-        >>> import ibis
-        >>> con = ibis.athena.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
-        <... object at 0x...>
-        >>> con.list_tables(database="my_database")
-        ['baz']
-
-        """
         table_loc = self._to_sqlglot_table(database)
 
         catalog = table_loc.catalog or self.current_catalog