refactor(sql): deprecate schema kwarg in insert

`schema` as a hierarchical term is deprecated in `insert`.
It will be removed Ibis 10.0.

refactor(bigquery): deprecate `schema` kwarg in insert

refactor(snowflake): deprecate `schema` kwarg in insert

ibis/backends/bigquery/__init__.py

@@ -714,11 +714,14 @@ def insert(
             If `True` then replace existing contents of table
 
         """
+        table_loc = self._warn_and_create_table_loc(database, schema)
+        catalog, db = self._to_catalog_db_tuple(table_loc)
+
         return super().insert(
             table_name,
             obj,
-            schema=schema if schema is not None else self.current_database,
-            database=database if database is not None else self.current_catalog,
+            schema=db if db is not None else self.current_database,
+            database=catalog if catalog is not None else self.current_catalog,
             overwrite=overwrite,
         )
 

ibis/backends/snowflake/__init__.py

@@ -1040,16 +1040,34 @@ def insert(
             The source data or expression to insert
         schema
             The name of the schema that the table is located in
+        schema
+            [deprecated] The name of the schema that the table is located in
         database
             Name of the attached database that the table is located in.
+
+            For multi-level table hierarchies, you can pass in a dotted string
+            path like `"catalog.database"` or a tuple of strings like
+            `("catalog", "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.
+            :::
         overwrite
             If `True` then replace existing contents of table
 
         """
+        table_loc = self._warn_and_create_table_loc(database, schema)
+        catalog, db = self._to_catalog_db_tuple(table_loc)
+
         if not isinstance(obj, ir.Table):
             obj = ibis.memtable(obj)
 
-        table = sg.table(table_name, db=schema, catalog=database, quoted=True)
+        table = sg.table(table_name, db=db, catalog=catalog, quoted=True)
         self._run_pre_execute_hooks(obj)
         query = sg.exp.insert(
             expression=self.compile(obj),

ibis/backends/sql/__init__.py

@@ -398,15 +398,31 @@ def insert(
         obj
             The source data or expression to insert
         schema
-            The name of the schema that the table is located in
+            [deprecated] The name of the schema that the table is located in
         database
             Name of the attached database that the table is located in.
+
+            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")`.
+
+            ::: {.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.
+            :::
         overwrite
             If `True` then replace existing contents of table
 
         """
+        table_loc = self._warn_and_create_table_loc(database, schema)
+        catalog, db = self._to_catalog_db_tuple(table_loc)
+
         if overwrite:
-            self.truncate_table(table_name, schema=schema, database=database)
+            self.truncate_table(table_name, schema=db, database=catalog)
 
         if not isinstance(obj, ir.Table):
             obj = ibis.memtable(obj)
@@ -417,7 +433,7 @@ def insert(
         quoted = compiler.quoted
         query = sge.insert(
             expression=self.compile(obj),
-            into=sg.table(table_name, db=schema, catalog=database, quoted=quoted),
+            into=sg.table(table_name, db=db, catalog=catalog, quoted=quoted),
             columns=[
                 sg.to_identifier(col, quoted=quoted)
                 for col in self.get_schema(table_name).names