I/O: API improvements: ctk {load,save} table becomes ctk {load,save}

Also, the `--cluster-url` option becomes optional. That's a much more
concise interface now.

Author: amotl

CHANGES.md

@@ -1,6 +1,9 @@
 # Changelog
 
 ## Unreleased
+- I/O: API improvements: `ctk {load,save} table` became `ctk {load,save}`
+  Also, the `--cluster-url` option becomes optional. That's a much more
+  concise interface now.
 
 ## 2026/03/13 v0.0.45
 - I/O: Refactored `ctk.io` subsystem

cratedb_toolkit/cluster/core.py

@@ -350,7 +350,7 @@ def load_table(
         Synopsis
         --------
         export CRATEDB_CLUSTER_ID=95998958-4d96-46eb-a77a-a894e7dde128
-        ctk load table https://cdn.crate.io/downloads/datasets/cratedb-datasets/cloud-tutorials/data_weather.csv.gz
+        ctk load https://cdn.crate.io/downloads/datasets/cratedb-datasets/cloud-tutorials/data_weather.csv.gz
 
         https://console.cratedb.cloud
         """
@@ -360,7 +360,7 @@ def load_table(
         target = target or TableAddress()
 
         if self.cluster_id is None:
-            raise DatabaseAddressMissingError("Need cluster identifier to load table")
+            raise DatabaseAddressMissingError("Need cluster identifier to load data")
 
         try:
             cio = CloudIo(cluster_id=self.cluster_id)
@@ -539,10 +539,10 @@ def load_table(
         --------
         export CRATEDB_CLUSTER_URL=crate://crate@localhost:4200/testdrive/demo
 
-        ctk load table influxdb2://example:token@localhost:8086/testdrive/demo
-        ctk load table mongodb://localhost:27017/testdrive/demo
-        ctk load table kinesis+dms:///arn:aws:kinesis:eu-central-1:831394476016:stream/testdrive
-        ctk load table kinesis+dms:///path/to/dms-over-kinesis.jsonl
+        ctk load influxdb2://example:token@localhost:8086/testdrive/demo
+        ctk load mongodb://localhost:27017/testdrive/demo
+        ctk load kinesis+dms:///arn:aws:kinesis:eu-central-1:831394476016:stream/testdrive
+        ctk load kinesis+dms:///path/to/dms-over-kinesis.jsonl
         """
 
         self._load_table_result = self._router.load_table(
@@ -563,7 +563,7 @@ def save_table(
         --------
         export CRATEDB_CLUSTER_URL=crate://crate@localhost:4200/testdrive/demo
 
-        ctk save table \
+        ctk save \
           "file+iceberg://./var/lib/iceberg/?catalog=default&namespace=demo&table=taxi_dataset"
         """
 

cratedb_toolkit/io/cli.py

@@ -3,30 +3,20 @@
 from pathlib import Path
 
 import click
-from click_aliases import ClickAliasedGroup
 
 from cratedb_toolkit.cluster.core import DatabaseCluster
 from cratedb_toolkit.model import InputOutputResource, TableAddress
 from cratedb_toolkit.option import option_cluster_id, option_cluster_name, option_cluster_url
-from cratedb_toolkit.util.cli import boot_click, make_command
+from cratedb_toolkit.util.cli import boot_click
 
 logger = logging.getLogger(__name__)
 
 
-@click.group(cls=ClickAliasedGroup)  # type: ignore[arg-type]
+@click.command()
+@click.argument("source_url")
+@click.argument("target_url", required=False)
 @click.option("--verbose", is_flag=True, required=False, help="Turn on logging")
 @click.option("--debug", is_flag=True, required=False, help="Turn on logging with debug level")
-@click.version_option()
-@click.pass_context
-def cli_load(ctx: click.Context, verbose: bool, debug: bool):
-    """
-    Load data into CrateDB.
-    """
-    return boot_click(ctx, verbose, debug)
-
-
-@make_command(cli_load, name="table")
-@click.argument("url")
 @option_cluster_id
 @option_cluster_name
 @option_cluster_url
@@ -36,9 +26,10 @@ def cli_load(ctx: click.Context, verbose: bool, debug: bool):
 @click.option("--compression", type=str, required=False, help="Compression format of the import resource")
 @click.option("--transformation", type=Path, required=False, help="Path to Tikray transformation file")
 @click.pass_context
-def load_table(
+def cli_load(
     ctx: click.Context,
-    url: str,
+    source_url: str,
+    target_url: str,
     cluster_id: str,
     cluster_name: str,
     cluster_url: str,
@@ -47,20 +38,30 @@ def load_table(
     format_: str,
     compression: str,
     transformation: t.Union[Path, None],
+    verbose: bool,
+    debug: bool,
 ):
     """
-    Import data into CrateDB and CrateDB Cloud clusters.
+    Load data into CrateDB.
     """
 
+    boot_click(ctx, verbose, debug)
+
+    # API evolution adjustments.
+    if target_url and cluster_url and target_url != cluster_url:
+        raise click.UsageError("Specify cluster URL either as TARGET_URL or --cluster-url, not both.")
+    if target_url:
+        cluster_url = target_url
+
     # When `--transformation` is given, but empty, fix it.
     if transformation is not None and transformation.name == "":
         transformation = None
 
     # Encapsulate source and target parameters.
-    source = InputOutputResource(url=url, format=format_, compression=compression)
+    source = InputOutputResource(url=source_url, format=format_, compression=compression)
     target = TableAddress(schema=schema, table=table)
 
-    # Dispatch "load table" operation.
+    # Dispatch "load" operation.
     cluster = DatabaseCluster.create(
         cluster_id=cluster_id,
         cluster_name=cluster_name,
@@ -69,49 +70,58 @@ def load_table(
     cluster.load_table(source=source, target=target, transformation=transformation)
 
 
-@click.group(cls=ClickAliasedGroup)  # type: ignore[arg-type]
+@click.command()
+@click.argument("source_url", required=False)
+@click.argument("target_url", required=False)
 @click.option("--verbose", is_flag=True, required=False, help="Turn on logging")
 @click.option("--debug", is_flag=True, required=False, help="Turn on logging with debug level")
-@click.version_option()
-@click.pass_context
-def cli_save(ctx: click.Context, verbose: bool, debug: bool):
-    """
-    Export data from CrateDB.
-    """
-    return boot_click(ctx, verbose, debug)
-
-
-@make_command(cli_save, name="table")
-@click.argument("url")
 @option_cluster_id
 @option_cluster_name
 @option_cluster_url
 @click.option("--format", "format_", type=str, required=False, help="File format of the export resource")
 @click.option("--compression", type=str, required=False, help="Compression format of the export resource")
 @click.option("--transformation", type=Path, required=False, help="Path to Tikray transformation file")
 @click.pass_context
-def save_table(
+def cli_save(
     ctx: click.Context,
-    url: str,
+    source_url: t.Optional[str],
+    target_url: t.Optional[str],
     cluster_id: str,
     cluster_name: str,
     cluster_url: str,
     format_: str,
     compression: str,
     transformation: t.Union[Path, None],
+    verbose: bool,
+    debug: bool,
 ):
     """
-    Export data from CrateDB and CrateDB Cloud clusters.
+    Export data from CrateDB.
     """
 
+    boot_click(ctx, verbose, debug)
+
+    # API evolution adjustments.
+    if source_url and not target_url:
+        target_url = source_url
+        source_url = None
+    if source_url and cluster_url and source_url != cluster_url:
+        raise click.UsageError("Specify cluster URL either as SOURCE_URL or --cluster-url, not both.")
+    if source_url:
+        cluster_url = source_url
+    if not target_url:
+        raise click.UsageError(
+            "Missing TARGET_URL. Use `ctk save <target-url>` or `ctk save <cluster-url> <target-url>`."
+        )
+
     # When `--transformation` is given, but empty, fix it.
     if transformation is not None and transformation.name == "":
         transformation = None
 
     # Encapsulate source and target parameters.
-    target = InputOutputResource(url=url, format=format_, compression=compression)
+    target = InputOutputResource(url=target_url, format=format_, compression=compression)
 
-    # Dispatch "save table" operation.
+    # Dispatch "save" operation.
     cluster = DatabaseCluster.create(
         cluster_id=cluster_id,
         cluster_name=cluster_name,

cratedb_toolkit/io/deltalake/__init__.py

@@ -102,9 +102,9 @@ def from_deltalake(source_url, target_url, progress: bool = False):
     See also: https://docs.pola.rs/api/python/stable/reference/api/polars.scan_delta.html
 
     # Synopsis: Load from filesystem.
-    ctk load table \
+    ctk load \
         "file+deltalake://./var/lib/delta" \
-        --cluster-url="crate://crate@localhost:4200/demo/taxi"
+        "crate://crate@localhost:4200/demo/taxi"
     """
     source = DeltaLakeAddress.from_url(source_url)
     logger.info(f"DeltaLake address: {source.location}")
@@ -123,8 +123,8 @@ def to_deltalake(source_url, target_url, progress: bool = False):
     See also: https://docs.pola.rs/api/python/stable/reference/api/polars.DataFrame.write_delta.html
 
     # Synopsis: Save to filesystem.
-    ctk save table \
-        --cluster-url="crate://crate@localhost:4200/demo/taxi" \
+    ctk save \
+        "crate://crate@localhost:4200/demo/taxi" \
         "file+deltalake://./var/lib/delta"
     """
 

cratedb_toolkit/io/dynamodb/api.py

@@ -11,13 +11,13 @@ def dynamodb_copy(source_url, target_url, progress: bool = False):
     Synopsis
     --------
     export CRATEDB_CLUSTER_URL=crate://crate@localhost:4200/testdrive/demo
-    ctk load table dynamodb://AWS_ACCESS_KEY:AWS_SECRET_ACCESS_KEY@localhost:4566/us-east-1/ProductCatalog
-    ctk load table dynamodb://AWS_ACCESS_KEY:AWS_SECRET_ACCESS_KEY@localhost:4566/arn:aws:dynamodb:us-east-1:000000000000:table/ProductCatalog
+    ctk load dynamodb://AWS_ACCESS_KEY:AWS_SECRET_ACCESS_KEY@localhost:4566/us-east-1/ProductCatalog
+    ctk load dynamodb://AWS_ACCESS_KEY:AWS_SECRET_ACCESS_KEY@localhost:4566/arn:aws:dynamodb:us-east-1:000000000000:table/ProductCatalog
 
-    ctk load table dynamodb://arn:aws:dynamodb:us-east-1:000000000000:table/ProductCatalog
-                              arn:aws:dynamodb:us-east-1:841394475918:table/stream-demo
+    ctk load dynamodb://arn:aws:dynamodb:us-east-1:000000000000:table/ProductCatalog
+    ctk load dynamodb://arn:aws:dynamodb:us-east-1:841394475918:table/stream-demo
 
-    ctk load table dynamodb://LSIAQAAAAAAVNCBMPNSG:dummy@localhost:4566/ProductCatalog?region=eu-central-1
+    ctk load dynamodb://LSIAQAAAAAAVNCBMPNSG:dummy@localhost:4566/ProductCatalog?region=eu-central-1
 
     Resources
     ---------

cratedb_toolkit/io/iceberg/__init__.py

@@ -156,9 +156,9 @@ def from_iceberg(source_url, target_url, progress: bool = False):
     See also: https://docs.pola.rs/api/python/stable/reference/api/polars.scan_iceberg.html
 
     # Synopsis: Load from metadata file on filesystem.
-    ctk load table \
+    ctk load \
         "file+iceberg://./iceberg/demo/taxi/metadata/00001-79d5b044-8bce-46dd-b21c-83679a01c986.metadata.json" \
-        --cluster-url="crate://crate@localhost:4200/demo/taxi"
+        "crate://crate@localhost:4200/demo/taxi"
     """
     source = IcebergAddress.from_url(source_url)
     logger.info(f"Iceberg address: {source.location}")
@@ -177,8 +177,8 @@ def to_iceberg(source_url, target_url, progress: bool = False):
     See also: https://pandas.pydata.org/docs/dev/reference/api/pandas.DataFrame.to_iceberg.html
 
     # Synopsis: Save to filesystem.
-    ctk save table \
-        --cluster-url="crate://crate@localhost:4200/demo/taxi" \
+    ctk save \
+        "crate://crate@localhost:4200/demo/taxi" \
         "file+iceberg://./iceberg/?catalog=default&namespace=demo&table=taxi"
     """
 

cratedb_toolkit/io/influxdb/__init__.py

@@ -10,7 +10,7 @@ def influxdb_copy(source_url, target_url, progress: bool = False):
     Synopsis
     --------
     export CRATEDB_CLUSTER_URL=crate://crate@localhost:4200/testdrive/demo
-    ctk load table influxdb2://example:token@localhost:8086/testdrive/demo
+    ctk load influxdb2://example:token@localhost:8086/testdrive/demo
     """
 
     # Invoke copy operation.

cratedb_toolkit/io/ingestr/api.py

@@ -51,17 +51,17 @@ def ingestr_copy(source_url: str, target_address: DatabaseAddress, progress: boo
 
     Synopsis:
 
-        ctk load table \
+        ctk load \
             "frankfurter://?base=EUR&table=latest" \
-            --cluster-url="crate://crate:na@localhost:4200/testdrive/exchange_latest"
+            "crate://crate:na@localhost:4200/testdrive/exchange_latest"
 
-        ctk load table \
+        ctk load \
             "frankfurter://?base=EUR&table=currencies" \
-            --cluster-url="crate://crate:na@localhost:4200/testdrive/exchange_currencies"
+            "crate://crate:na@localhost:4200/testdrive/exchange_currencies"
 
-        ctk load table \
+        ctk load \
             "postgresql://pguser:secret11@postgresql.example.org:5432/postgres?table=public.diamonds" \
-            --cluster-url="crate://crate:na@localhost:4200/testdrive/ibis_diamonds"
+            "crate://crate:na@localhost:4200/testdrive/ibis_diamonds"
     """
     ingestr_available, ingestr, ConfigFieldMissingException = _get_ingestr()
 

cratedb_toolkit/io/mongodb/api.py

@@ -32,7 +32,7 @@ def mongodb_copy_migr8(
     Synopsis
     --------
     export CRATEDB_CLUSTER_URL=crate://crate@localhost:4200/testdrive/demo
-    ctk load table mongodb://localhost:27017/testdrive/demo
+    ctk load mongodb://localhost:27017/testdrive/demo
 
     Backlog
     -------
@@ -115,7 +115,7 @@ def mongodb_copy(
     Synopsis
     --------
     export CRATEDB_CLUSTER_URL=crate://crate@localhost:4200/testdrive/demo
-    ctk load table mongodb://localhost:27017/testdrive/demo
+    ctk load mongodb://localhost:27017/testdrive/demo
     """
 
     logger.info(f"mongodb_copy. source={source_url}, target={target_url}")
@@ -196,7 +196,7 @@ def mongodb_relay_cdc(
     Synopsis
     --------
     export CRATEDB_CLUSTER_URL=crate://crate@localhost:4200/testdrive/demo-cdc
-    ctk load table mongodb+cdc://localhost:27017/testdrive/demo
+    ctk load mongodb+cdc://localhost:27017/testdrive/demo
 
     Backlog
     -------

cratedb_toolkit/io/router.py

@@ -38,10 +38,10 @@ def load_table(
         --------
         export CRATEDB_CLUSTER_URL=crate://crate@localhost:4200/testdrive/demo
 
-        ctk load table influxdb2://example:token@localhost:8086/testdrive/demo
-        ctk load table mongodb://localhost:27017/testdrive/demo
-        ctk load table kinesis+dms:///arn:aws:kinesis:eu-central-1:831394476016:stream/testdrive
-        ctk load table kinesis+dms:///path/to/dms-over-kinesis.jsonl
+        ctk load influxdb2://example:token@localhost:8086/testdrive/demo
+        ctk load mongodb://localhost:27017/testdrive/demo
+        ctk load kinesis+dms:///arn:aws:kinesis:eu-central-1:831394476016:stream/testdrive
+        ctk load kinesis+dms:///path/to/dms-over-kinesis.jsonl
         """
         source_url = source.url
         target_url = target.dburi
@@ -140,7 +140,7 @@ def save_table(
         --------
         export CRATEDB_CLUSTER_URL=crate://crate@localhost:4200/testdrive/demo
 
-        ctk save table \
+        ctk save \
           "file+iceberg://./var/lib/iceberg/?catalog=default&namespace=demo&table=taxi_dataset"
         """
         source_url = source.dburi