diff --git a/README.md b/README.md index a90919f..33b616d 100644 --- a/README.md +++ b/README.md @@ -67,7 +67,7 @@ con = ibis.hotdata.connect( verify_ssl=True, # False to skip TLS verification, or path to CA bundle default_connection=None, # default catalog (connection id); auto-detected if only one exists default_schema=None, # default schema; auto-detected if only one exists - database_id=None, # bind an existing managed database id at connect time + database_id=None, # bind an existing instant database id at connect time poll_interval_s=0.25, # polling interval for async queries poll_timeout_s=600.0, # max time to wait for a query result ) @@ -83,9 +83,9 @@ con = ibis.connect( ) ``` -## Managed databases +## Instant databases -Managed databases are the primary way to bring data into Hotdata with Ibis. Declare a database and its tables, upload data, and query immediately. +Instant databases are the primary way to bring data into Hotdata with Ibis. Declare a database and its tables, upload data, and query immediately. ### Create and load diff --git a/examples/04_ibis_table_workflows.py b/examples/04_ibis_table_workflows.py index 1c90e39..63bc1e2 100644 --- a/examples/04_ibis_table_workflows.py +++ b/examples/04_ibis_table_workflows.py @@ -9,7 +9,7 @@ (multi-column projections, joins across tables, filters, ordering) -- not just a single trivial column. -Ad hoc/federated querying (raw ``Connection`` tables, no managed database) is +Ad hoc/federated querying (raw ``Connection`` tables, no instant database) is not used here: it's a deprecated path, and every query now requires a database scope server-side regardless. @@ -40,7 +40,7 @@ def setup(api_url: str, token: str, workspace_id: str) -> str: - """Create the managed database and load small customer/orders tables.""" + """Create the instant database and load small customer/orders tables.""" con = ibis.hotdata.connect(api_url=api_url, token=token, workspace_id=workspace_id) database_id = con.create_database(DATABASE, tables=["customer", "orders"], schema=SCHEMA) @@ -120,7 +120,7 @@ def main() -> None: token = os.environ["HOTDATA_API_KEY"] workspace_id = os.environ["HOTDATA_WORKSPACE"] - print("== SETUP (managed database: customer, orders) ==") + print("== SETUP (instant database: customer, orders) ==") database_id = setup(API_BASE_URL, token, workspace_id) print(f"created database_id={database_id}") diff --git a/examples/05_roundtrip_demo.py b/examples/05_roundtrip_demo.py index ace447e..c25609b 100644 --- a/examples/05_roundtrip_demo.py +++ b/examples/05_roundtrip_demo.py @@ -1,7 +1,7 @@ #!/usr/bin/env python3 -"""Ibis <-> Hotdata round trip: create a managed database, upload data, read it back. +"""Ibis <-> Hotdata round trip: create an instant database, upload data, read it back. -Demonstrates the managed-database read contract that ``hotdata-dlt-destination``'s +Demonstrates the instant-database read contract that ``hotdata-dlt-destination``'s live ibis backend depends on: bind ``database_id`` (the id returned by ``create_database``, not its display name -- Hotdata database names are not unique) at connect time, then read through the ``"default"`` catalog -- both @@ -34,7 +34,7 @@ def write(api_url: str, token: str, workspace_id: str) -> str: - """Create the managed database and upload a small pandas DataFrame into it.""" + """Create the instant database and upload a small pandas DataFrame into it.""" con = ibis.hotdata.connect(api_url=api_url, token=token, workspace_id=workspace_id) database_id = con.create_database(DATABASE, tables=["spans"], schema=SCHEMA) @@ -97,7 +97,7 @@ def main() -> None: database_id = write(API_BASE_URL, token, workspace_id) print(f"created database_id={database_id}") - print("\n== READ, via the managed-database contract ==") + print("\n== READ, via the instant-database contract ==") read_via_ibis(API_BASE_URL, token, workspace_id, database_id) print("\n== CLEANUP ==") diff --git a/src/ibis_hotdata/backend.py b/src/ibis_hotdata/backend.py index 501d347..24e7725 100644 --- a/src/ibis_hotdata/backend.py +++ b/src/ibis_hotdata/backend.py @@ -170,7 +170,7 @@ def do_connect( Optional default **database** (remote schema name). If omitted and only one schema exists for the default connection, it is chosen automatically. database_id - Optional managed database id to bind at connect time. When set, all + Optional instant database id to bind at connect time. When set, all queries use this database's ``X-Database-Id`` header and ``"default"`` catalog references resolve to the underlying connection automatically — without needing to call ``create_table`` first. @@ -335,7 +335,7 @@ def _resolve_connection(self, name_or_id: str) -> dict[str, Any]: raise com.IbisError(f"Unknown Hotdata connection {name_or_id!r}") def _find_managed_connection(self, database_id: str) -> dict[str, Any] | None: - """Look up a managed database by id. + """Look up an instant database by id. Returns the detail dict if found, ``None`` if not found. Raises :class:`~ibis.common.exceptions.IbisError` on API failures. @@ -348,10 +348,10 @@ def _find_managed_connection(self, database_id: str) -> dict[str, Any] | None: raise _ibis_err_from_hotdata(exc) from exc def _resolve_managed_connection(self, database_id: str) -> dict[str, Any]: - """Resolve a managed database by id, returning its detail dict.""" + """Resolve an instant database by id, returning its detail dict.""" result = self._find_managed_connection(database_id) if result is None: - raise com.IbisError(f"Unknown managed database {database_id!r}") + raise com.IbisError(f"Unknown instant database {database_id!r}") return result def _managed_table_synced( @@ -399,15 +399,15 @@ def _table_location( db_record = self._resolve_managed_connection(conn) conn_id = db_record["default_connection_id"] # Always update both cached values so they stay in sync across multiple - # create_table / drop_table calls, even if different managed databases are used. + # create_table / drop_table calls, even if different instant databases are used. self._database_id = db_record["id"] self._database_connection_id = conn_id return conn_id, schema def _resolve_database_connection_id(self) -> str | None: - """Return the actual connection_id for the current managed database context. + """Return the actual connection_id for the current instant database context. - Managed database SQL uses ``"default"`` as the catalog, but the information + Instant database SQL uses ``"default"`` as the catalog, but the information schema REST API still needs the real ``connection_id``. This method resolves that mapping lazily and caches the result. """ @@ -432,7 +432,7 @@ def get_schema( ) -> sch.Schema: conn = catalog or self.current_catalog schema_name = database or self.current_database - # Managed database tables use "default" as the SQL catalog but the info + # Instant database tables use "default" as the SQL catalog but the info # schema REST API needs the real connection_id. api_conn = ( (self._resolve_database_connection_id() or conn) @@ -665,7 +665,7 @@ def create_table( ) -> ir.Table: """Upload local data into a declared managed table. - ``database``'s first element must be the managed database id returned + ``database``'s first element must be the instant database id returned by ``create_database``, not its display name — Hotdata database names are not unique. @@ -679,7 +679,7 @@ def create_table( data = self._local_table_to_parquet(obj, schema) connection_id, schema_name = self._table_location(database) # Cache the resolved connection_id so get_schema can use it for info schema - # API calls when the "default" catalog is used in managed database contexts. + # API calls when the "default" catalog is used in instant database contexts. self._database_connection_id = connection_id if not overwrite and self._managed_table_synced(connection_id, schema_name, name): raise com.IbisInputError( @@ -695,7 +695,7 @@ def create_table( ) except HotdataAPIError as exc: raise _ibis_err_from_hotdata(exc) from exc - # Managed database SQL requires "default" as the catalog prefix, not the + # Instant database SQL requires "default" as the catalog prefix, not the # raw connection_id. _table_location always sets _database_id when resolving # a managed connection, so we can always use the "default" catalog here. return self.table(name, database=("default", schema_name)) diff --git a/src/ibis_hotdata/http.py b/src/ibis_hotdata/http.py index 5a7a595..ca43862 100644 --- a/src/ibis_hotdata/http.py +++ b/src/ibis_hotdata/http.py @@ -221,7 +221,7 @@ def create_managed_database( schema: str = "public", tables: Sequence[str] = (), ) -> dict[str, Any]: - """POST ``/v1/databases`` — creates a managed database. + """POST ``/v1/databases`` — creates an instant database. The database is created with an auto-provisioned default catalog. """ diff --git a/tests/test_hotdata_backend.py b/tests/test_hotdata_backend.py index 5865857..cc670aa 100644 --- a/tests/test_hotdata_backend.py +++ b/tests/test_hotdata_backend.py @@ -17,7 +17,7 @@ from conftest import mock_presigned_upload_flow from pytest_httpserver import HTTPServer -# Managed database identifiers for mocked Hotdata (SQL shape ``sales.public.orders``). +# Instant database identifiers for mocked Hotdata (SQL shape ``sales.public.orders``). MANAGED_DB_ID = "db_sales" # databases API id MANAGED_CONN = "conn_sales" # default_connection_id (backing connection for loads) MANAGED_NAME = "sales" # description @@ -595,12 +595,12 @@ def test_drop_table_raises_for_unknown_database(httpserver: HTTPServer, srv: str con = ibis.hotdata.connect(api_url=srv, token="tok", workspace_id="ws", verify_ssl=False) - with pytest.raises(com.IbisError, match="Unknown managed database"): + with pytest.raises(com.IbisError, match="Unknown instant database"): con.drop_table("demo", database=(TPCH_CONN, PUBLIC)) def test_drop_table_force_ignores_unknown_database(httpserver: HTTPServer, srv: str): - # force=True silently swallows the "Unknown managed database" IbisError + # force=True silently swallows the "Unknown instant database" IbisError httpserver.expect_request(f"/v1/databases/{TPCH_CONN}").respond_with_data( json.dumps({"detail": "not found"}), status=404, content_type="application/json" )