maxc-cli 0.1.0__tar.gz → 0.1.1__tar.gz

{maxc_cli-0.1.0 → maxc_cli-0.1.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: maxc-cli
-Version: 0.1.0
+Version: 0.1.1
 Summary: Agent-native MaxCompute CLI for external coding agents
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.8

{maxc_cli-0.1.0 → maxc_cli-0.1.1}/setup.py

@@ -9,7 +9,7 @@ README = ROOT / "README.md"
 
 setup(
     name="maxc-cli",
-    version="0.1.0",
+    version="0.1.1",
     description="Agent-native MaxCompute CLI for external coding agents",
     long_description=README.read_text(encoding="utf-8"),
     long_description_content_type="text/markdown",

{maxc_cli-0.1.0 → maxc_cli-0.1.1}/skills/use-maxc-cli/SKILL.md

@@ -63,7 +63,7 @@ Then follow the corresponding section in [references/bootstrap-auth.md](referenc
    - `configured=false` → no auth set up → **ask which method** (see Bootstrap Flow above).
    - `configured=true, validation_status=failed` → config exists but remote check failed → inspect warnings, then fix or re-login.
 3. Read [references/bootstrap-auth.md](references/bootstrap-auth.md) for auth paths.
-4. If `meta list-tables --json` returns `cache_miss`, run `cache build --json` first.
+4. `meta list-tables --json` falls back to live queries on cache miss. Run `cache build --json` to speed up repeat queries.
 5. Read [references/command-patterns.md](references/command-patterns.md) for command syntax and output shapes.
 
 ## Working Rules
@@ -75,7 +75,8 @@ Then follow the corresponding section in [references/bootstrap-auth.md](referenc
 - Trust runtime help and actual command output over stale snippets.
 - Never install or upgrade Python without explicit user confirmation.
 - Prefer `auth login` over hand-editing `~/.maxc/config.yaml`.
-- `meta list-tables` is cache-backed; returns `cache_miss` on cold cache.
+- `meta list-tables` is cache-backed; falls back to live backend query on cache miss.
+- Most meta commands support `--schema` to override the session default (list-tables, search, search-columns).
 - `session set/show/unset` are local-only — no authenticated backend required.
 - `agent context` is a fast local config summary; does not enumerate tables.
 - Use normalized `data` shapes: `auth whoami` → `data.identity`, `query`/`job result` → `data.result`, `meta describe` → `data.table`, `data sample` → `data.sample`.
@@ -87,7 +88,7 @@ Then follow the corresponding section in [references/bootstrap-auth.md](referenc
 |---------|-----------------|
 | Using `auth login --from-env` without checking env vars exist | Run `auth whoami --json` first; only use `--from-env` when env vars are confirmed set |
 | Hand-editing `~/.maxc/config.yaml` | Use `auth login` |
-| Calling `meta list-tables` on a cold cache | Run `cache build --json` first |
+| Calling `meta list-tables` on a cold cache | Tables are fetched live on cache miss; `cache build` improves speed for repeat queries |
 | Inventing endpoints | Only use endpoints the user provided or that exist in current config |
 | Using `job wait --stream` and expecting a JSON envelope | `--stream` emits NDJSON; use plain `job wait --json` for envelope |
 | Running a query without checking cost first | Use `query cost` before large queries; use `--cost-check` to set auto-abort threshold |
@@ -146,6 +147,60 @@ maxc session unset --json
 
 Session overrides are stored in `~/.maxc/session_override.yaml` and take priority over config files and env vars for project/schema only.
 
+## Schema Operations
+
+For projects with 3-tier namespace (project.schema.table):
+
+```bash
+# List available schemas
+maxc meta list-schemas --json
+
+# List tables in a specific schema (two approaches)
+maxc meta list-tables --schema california_schools --json        # one-shot
+maxc session set --schema california_schools --json             # sticky session
+
+# Search within a schema
+maxc meta search school --schema california_schools --json
+maxc meta search-columns county --schema california_schools --json
+
+# Build cache for a specific schema
+maxc cache build --schema california_schools --json
+
+# Describe a table (use schema.table_name format)
+maxc meta describe california_schools.frpm --json
+
+# Reset to default schema
+maxc session unset --json
+```
+
+When `--schema` is given, it overrides `session set --schema`. When neither is set, the project default schema is used.
+
+## Cache Mechanism
+
+The metadata cache accelerates `list-tables`, `search`, `search-columns`, and `describe`.
+
+- **How it works**: `cache build` fetches all table metadata from MaxCompute and stores it in a local SQLite DB (`~/.maxc/cache/cache.db`). Subsequent meta commands read from cache first.
+- **Cache key**: `(project, schema_name, table_name)` — schema is part of the key, so different schemas have independent caches.
+- **Cache miss behavior**: `list-tables` and `search` fall back to live backend queries on cache miss. No manual cache build is required, but caching speeds up repeated queries.
+- **When to rebuild**: After schema changes, new tables, or when cache is stale. Check with `cache status --json`.
+
+```bash
+maxc cache build --json                                # build for current project/schema
+maxc cache build --schema my_schema --json             # build for specific schema
+maxc cache status --json                               # check cache freshness
+maxc cache clear --json                                # wipe and rebuild
+```
+
+## Known Limitations
+
+| Feature | Status | Detail |
+|---------|--------|--------|
+| `meta lineage` | Placeholder | Returns `supported=false`; MaxCompute lineage API not yet integrated |
+| `list-tables` pagination | Not implemented | CLI-side `--cursor` is offset token, not server-side cursor |
+| `diff data` | Snapshot compare | Keyed snapshot compare, not exhaustive diff |
+| `auth login` | Plaintext YAML | AccessKey stored in `~/.maxc/config.yaml` (file permissions 0600) |
+| Write operations | Read-only | CLI enforces SELECT-only; DDL/DML not supported |
+
 ## Cost Control
 
 Before running large queries, always estimate cost first:
@@ -210,9 +265,26 @@ maxc diff data prod_table staging_table \
   --json
 ```
 
+## Troubleshooting
+
+| Symptom | Cause | Fix |
+|---------|-------|-----|
+| `list-tables` returns empty but tables exist | Wrong schema or no tables in default schema | Use `--schema <name>` or `session set --schema` |
+| `search` returns no matches | Keyword not in table/column names or descriptions | Try broader keywords; check with `list-tables --schema` first |
+| `cache build` reports 0 tables | Schema not specified for non-default schemas | Add `--schema <name>` |
+| `describe` fails with NOT_FOUND | Table in a different schema | Use `schema.table_name` format or set session schema |
+| Commands hang or timeout | Network/endpoint issue | Check `auth whoami --json` for endpoint; verify connectivity |
+
+When all else fails, verify with raw pyodps:
+```python
+from odps import ODPS
+o = ODPS(access_id, secret_key, project, endpoint)
+list(o.list_tables(schema='<schema_name>'))
+```
+
 ## Command Families
 
-- Bootstrap: `python3 --version`, `pip install maxc-cli`, `python3 -m maxc_cli --help`
+- Bootstrap: `python3 --version`, `pip install maxc-cli -i http://yum.tbsite.net/aliyun-pypi/simple --trusted-host yum.tbsite.net`, `python3 -m maxc_cli --help`
 - Auth and session: `auth whoami`, `auth login`, `auth can-i`, `session set/show/unset`
 - Metadata and data: `meta list-tables`, `meta describe`, `meta search`, `meta search-columns`, `meta latest-partition`, `meta freshness`, `meta partitions`, `meta list-projects`, `meta list-schemas`, `data sample`, `data profile`
 - Query and jobs: `query`, `query cost`, `query explain`, `job submit/status/wait/result/diagnose/cancel/list`

{maxc_cli-0.1.0 → maxc_cli-0.1.1}/skills/use-maxc-cli/references/setup-install.md

@@ -44,16 +44,20 @@ Do not install or upgrade Python proactively. First tell the user why the curren
 
 ## Step 2: Install `maxc-cli`
 
-Install with pip:
+`maxc-cli` 发布在内部 PyPI 仓库，安装时需要指定 index URL：
 
 ```bash
-python3 -m pip install --upgrade maxc-cli
+python3 -m pip install --upgrade maxc-cli \
+  -i http://yum.tbsite.net/aliyun-pypi/simple \
+  --trusted-host yum.tbsite.net
 ```
 
 If the environment requires a user-local install:
 
 ```bash
-python3 -m pip install --user --upgrade maxc-cli
+python3 -m pip install --user --upgrade maxc-cli \
+  -i http://yum.tbsite.net/aliyun-pypi/simple \
+  --trusted-host yum.tbsite.net
 ```
 
 Verify install with either the console script or module path:

{maxc_cli-0.1.0 → maxc_cli-0.1.1}/src/maxc_cli/__init__.py

@@ -2,4 +2,4 @@
 
 __all__ = ["__version__"]
 
-__version__ = "0.1.0"
+__version__ = "0.1.1"

{maxc_cli-0.1.0 → maxc_cli-0.1.1}/src/maxc_cli/app.py

@@ -820,12 +820,16 @@ class MaxCApp:
         self.log("job.list", envelope.status, envelope.metadata)
         return envelope
 
-    def meta_list_tables(self) -> 'Envelope':
+    def meta_list_tables(self, *, schema: 'str | None' = None) -> 'Envelope':
         started = monotonic()
-        
+        effective_schema = schema or self.config.default_schema
+
         # Try to get from cache first
-        cached_tables = self.cache.get_all_cached_tables(self.config.default_project)
-        
+        cached_tables = self.cache.get_all_cached_tables(
+            self.config.default_project,
+            schema_name=effective_schema,
+        )
+
         if cached_tables:
             # Use cached data (returns list of dicts)
             tables = cached_tables
@@ -845,22 +849,20 @@ class MaxCApp:
                 for table in tables
             ]
         else:
-            # No cache - return guidance to build cache first
-            return Envelope(
-                command="meta.list-tables",
-                status="cache_miss",
-                data={"tables": [], "total": 0},
-                metadata=self._cache_metadata(
-                    project=self.config.default_project,
-                    source="none",
-                    query_time_ms=int((monotonic() - started) * 1000),
-                ),
-                agent_hints=AgentHints(
-                    next_actions=["cache.build"],
-                    insights=["No metadata cache found for this project. Building the cache first will significantly improve performance."],
-                    warnings=["Cache miss: Run `maxc cache build` to populate the metadata cache."],
-                ),
-            )
+            # Cache miss — fall back to live backend query
+            live_tables = self.backend.list_tables(schema=effective_schema)
+            source = "backend"
+            rows = [
+                {
+                    "table_name": t.name,
+                    "table_type": t.table_type or "TABLE",
+                    "size_bytes": t.size_bytes,
+                    "owner": t.owner,
+                    "description": t.description,
+                    "partition_columns": [c.name for c in (t.partition_columns or [])],
+                }
+                for t in live_tables
+            ]
         
         metadata = self._cache_metadata(
             project=self.config.default_project,
@@ -981,14 +983,17 @@ class MaxCApp:
         self.log("meta.describe", envelope.status, envelope.metadata)
         return envelope
 
-    def meta_search(self, keyword: 'str') -> 'Envelope':
+    def meta_search(self, keyword: 'str', *, schema: 'str | None' = None) -> 'Envelope':
         started = monotonic()
-        cached_tables = self.cache.get_all_cached_tables(self.config.default_project)
+        effective_schema = schema or self.config.default_schema
+        cached_tables = self.cache.get_all_cached_tables(
+            self.config.default_project, schema_name=effective_schema,
+        )
         if cached_tables:
             matches = self._search_in_cache(keyword, cached_tables)
             source = "cache"
         else:
-            matches = self.backend.search_tables(keyword)
+            matches = self.backend.search_tables(keyword, schema=effective_schema)
             source = "live"
         envelope = Envelope(
             command="meta.search",
@@ -1007,14 +1012,17 @@ class MaxCApp:
         self.log("meta.search", envelope.status, envelope.metadata)
         return envelope
 
-    def meta_search_columns(self, keyword: 'str') -> 'Envelope':
+    def meta_search_columns(self, keyword: 'str', *, schema: 'str | None' = None) -> 'Envelope':
         started = monotonic()
-        cached_tables = self.cache.get_all_cached_tables(self.config.default_project)
+        effective_schema = schema or self.config.default_schema
+        cached_tables = self.cache.get_all_cached_tables(
+            self.config.default_project, schema_name=effective_schema,
+        )
         if cached_tables:
             matches = self._search_columns_in_cache(keyword, cached_tables)
             source = "cache"
         else:
-            matches = self.backend.search_columns(keyword)
+            matches = self.backend.search_columns(keyword, schema=effective_schema)
             source = "live"
         envelope = Envelope(
             command="meta.search-columns",
@@ -1361,11 +1369,8 @@ class MaxCApp:
                 }
             )
 
-        all_tables = self.backend.list_tables()
-        if schema_name:
-            tables = all_tables
-        else:
-            tables = all_tables
+        all_tables = self.backend.list_tables(schema=schema_name)
+        tables = all_tables
 
         if progress_callback is not None:
             progress_callback(

{maxc_cli-0.1.0 → maxc_cli-0.1.1}/src/maxc_cli/backend/meta.py

@@ -17,11 +17,14 @@ from ..helpers import (
 class MetaMixin:
     """Mixin providing metadata methods."""
 
-    def list_tables(self) -> 'list[TableDefinition]':
-        """List tables in the current project."""
+    def list_tables(self, *, schema: 'str | None' = None) -> 'list[TableDefinition]':
+        """List tables in the current project, optionally filtered by schema."""
         tables: 'list[TableDefinition]' = []
+        kwargs: 'dict[str, Any]' = {"project": self.project}
+        if schema:
+            kwargs["schema"] = schema
         try:
-            for table in self.client.list_tables(project=self.project):
+            for table in self.client.list_tables(**kwargs):
                 tables.append(self._table_stub(table))
         except Exception as exc:
             raise translate_odps_error(exc) from exc
@@ -37,11 +40,11 @@ class MetaMixin:
         definition.sample_rows = sample_rows
         return definition
 
-    def search_tables(self, keyword: 'str') -> 'list[dict[str, Any]]':
+    def search_tables(self, keyword: 'str', *, schema: 'str | None' = None) -> 'list[dict[str, Any]]':
         """Search tables by keyword."""
         tokens = [item.lower() for item in keyword.split() if item.strip()] or [keyword.lower()]
         matches: 'list[dict[str, Any]]' = []
-        for table in self.list_tables():
+        for table in self.list_tables(schema=schema):
             score = 0
             searchable = f"{table.name} {table.description}".lower()
             matched_columns: 'list[str]' = []
@@ -65,11 +68,11 @@ class MetaMixin:
                 )
         return sorted(matches, key=lambda item: (-item["score"], item["table_name"]))
 
-    def search_columns(self, keyword: 'str') -> 'list[dict[str, Any]]':
+    def search_columns(self, keyword: 'str', *, schema: 'str | None' = None) -> 'list[dict[str, Any]]':
         """Search columns by keyword."""
         tokens = [item.lower() for item in keyword.split() if item.strip()] or [keyword.lower()]
         matches: 'list[dict[str, Any]]' = []
-        for table in self.list_tables():
+        for table in self.list_tables(schema=schema):
             for column in table.columns:
                 score = 0
                 text = f"{column.name} {column.comment}".lower()
@@ -183,10 +186,13 @@ class MetaMixin:
 
     # Private methods for metadata handling
 
-    def _get_table(self, table_name: 'str', *, project: 'str | None' = None):
+    def _get_table(self, table_name: 'str', *, project: 'str | None' = None, schema: 'str | None' = None):
         """Get ODPS table by name."""
+        kwargs: 'dict[str, Any]' = {"project": project or self.project}
+        if schema:
+            kwargs["schema"] = schema
         try:
-            return self.client.get_table(table_name, project=project or self.project)
+            return self.client.get_table(table_name, **kwargs)
         except Exception as exc:
             raise translate_odps_error(exc) from exc
 

{maxc_cli-0.1.0 → maxc_cli-0.1.1}/src/maxc_cli/cli.py

@@ -121,6 +121,7 @@ def build_parser() -> 'argparse.ArgumentParser':
     meta_subparsers = _add_required_subparsers(meta_parser, dest="meta_command")
 
     meta_list = meta_subparsers.add_parser("list-tables", help="List tables")
+    meta_list.add_argument("--schema", help="Schema name (overrides session default)")
     meta_list.add_argument("--json", action="store_true", help="Output as JSON envelope")
     meta_list.set_defaults(handler=_handle_meta_list_tables)
 
@@ -132,11 +133,13 @@ def build_parser() -> 'argparse.ArgumentParser':
 
     meta_search = meta_subparsers.add_parser("search", help="Search tables")
     meta_search.add_argument("keyword", help="Search keyword")
+    meta_search.add_argument("--schema", help="Schema name (overrides session default)")
     meta_search.add_argument("--json", action="store_true", help="Output as JSON envelope")
     meta_search.set_defaults(handler=_handle_meta_search)
 
     meta_search_columns = meta_subparsers.add_parser("search-columns", help="Search columns")
     meta_search_columns.add_argument("keyword", help="Search keyword")
+    meta_search_columns.add_argument("--schema", help="Schema name (overrides session default)")
     meta_search_columns.add_argument("--json", action="store_true", help="Output as JSON envelope")
     meta_search_columns.set_defaults(handler=_handle_meta_search_columns)
 
@@ -542,7 +545,8 @@ def _handle_job_list(app: 'MaxCApp', args: 'argparse.Namespace', stdout: 'TextIO
 
 
 def _handle_meta_list_tables(app: 'MaxCApp', args: 'argparse.Namespace', stdout: 'TextIO') -> 'None':
-    envelope = app.meta_list_tables()
+    schema = getattr(args, "schema", None)
+    envelope = app.meta_list_tables(schema=schema)
     _emit_envelope(envelope, args=args, stdout=stdout, default_format="table")
 
 
@@ -552,12 +556,14 @@ def _handle_meta_describe(app: 'MaxCApp', args: 'argparse.Namespace', stdout: 'T
 
 
 def _handle_meta_search(app: 'MaxCApp', args: 'argparse.Namespace', stdout: 'TextIO') -> 'None':
-    envelope = app.meta_search(args.keyword)
+    schema = getattr(args, "schema", None)
+    envelope = app.meta_search(args.keyword, schema=schema)
     _emit_envelope(envelope, args=args, stdout=stdout, default_format="table")
 
 
 def _handle_meta_search_columns(app: 'MaxCApp', args: 'argparse.Namespace', stdout: 'TextIO') -> 'None':
-    envelope = app.meta_search_columns(args.keyword)
+    schema = getattr(args, "schema", None)
+    envelope = app.meta_search_columns(args.keyword, schema=schema)
     _emit_envelope(envelope, args=args, stdout=stdout, default_format="table")
 
 

{maxc_cli-0.1.0 → maxc_cli-0.1.1}/src/maxc_cli.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: maxc-cli
-Version: 0.1.0
+Version: 0.1.1
 Summary: Agent-native MaxCompute CLI for external coding agents
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.8

{maxc_cli-0.1.0 → maxc_cli-0.1.1}/src/maxc_cli.egg-info/SOURCES.txt

@@ -3,6 +3,7 @@ README.md
 pyproject.toml
 setup.py
 scripts/sync_codex_skill.py
+skills/use-maxc-cli/.DS_Store
 skills/use-maxc-cli/SKILL.md
 skills/use-maxc-cli/agents/openai.yaml
 skills/use-maxc-cli/references/bootstrap-auth.md

{maxc_cli-0.1.0 → maxc_cli-0.1.1}/tests/test_agent_hints_and_cli.py

@@ -169,7 +169,7 @@ def _table(name: 'str' = "sales.orders") -> 'TableDefinition':
 
 
 class _StubMetaBackend:
-    def list_tables(self) -> 'list[TableDefinition]':
+    def list_tables(self, *, schema: 'str | None' = None) -> 'list[TableDefinition]':
         return [_table()]
 
     def describe_table(self, table_name: 'str') -> 'TableDefinition':
@@ -190,19 +190,15 @@ def _make_app(tmp_path: 'Path') -> 'MaxCApp':
     return app
 
 
-def test_meta_list_tables_returns_cache_guidance_when_cache_is_empty(tmp_path: 'Path') -> 'None':
+def test_meta_list_tables_returns_live_results_when_cache_is_empty(tmp_path: 'Path') -> 'None':
     app = _make_app(tmp_path)
 
     envelope = app.meta_list_tables()
 
-    assert envelope.status == "cache_miss"
-    assert envelope.metadata["source"] == "none"
-    assert envelope.metadata["cache_available"] is False
-    assert envelope.to_dict()["data"] == {
-        "tables": [],
-        "pagination": {"total": 0, "has_more": False},
-    }
-    assert envelope.to_dict()["agent_hints"]["action_ids"] == ["cache.build"]
+    assert envelope.status == "success"
+    tables = envelope.to_dict()["data"]["tables"]
+    assert len(tables) == 1
+    assert tables[0]["table_name"] == "sales.orders"
 
 
 def test_cache_build_returns_clear_metadata_and_async_build_completes(tmp_path: 'Path') -> 'None':

{maxc_cli-0.1.0 → maxc_cli-0.1.1}/tests/test_cli_mock.py

@@ -1207,3 +1207,144 @@ def test_not_found_error_renders_markdown_without_json_flag(
     assert "**Error**" in err_text
     assert "`NOT_FOUND`" in err_text
     assert "**Suggestion**" in err_text
+
+
+# ============================================================
+# Schema Passthrough Tests
+# ============================================================
+
+
+class _SchemaAwareODPS(FakeODPS):
+    """Mock ODPS client that returns different tables per schema."""
+
+    _SCHEMA_TABLES = {
+        None: ["default_table_a", "default_table_b"],
+        "california_schools": ["frpm", "satscores", "schools"],
+    }
+
+    def list_tables(self, *, project=None, schema=None):
+        names = self._SCHEMA_TABLES.get(schema, [])
+        return [
+            type("FakeTable", (), {"name": n})()
+            for n in names
+        ]
+
+    def get_table(self, name, *, project=None, schema=None):
+        # minimal stub for describe
+        return type("FakeTable", (), {
+            "name": name,
+            "comment": "",
+            "table_schema": type("Schema", (), {"columns": [], "partitions": []})(),
+            "owner": "test_owner",
+            "creation_time": None,
+            "last_data_modified_time": None,
+            "is_virtual_view": False,
+            "size": 0,
+            "lifecycle": None,
+        })()
+
+
+def test_meta_list_tables_passes_schema_to_backend(
+    tmp_path: 'Path', monkeypatch
+) -> None:
+    """meta list-tables --schema should list tables from the specified schema."""
+    clear_odps_env(monkeypatch)
+    isolate_home(monkeypatch, tmp_path)
+    import odps
+    monkeypatch.setattr(odps, "ODPS", _SchemaAwareODPS)
+
+    config_path = _make_config_with_odps(tmp_path)
+    code, payload, _ = run_json_command(
+        tmp_path, config_path,
+        ["meta", "list-tables", "--schema", "california_schools", "--json"],
+    )
+
+    assert code == 0
+    assert payload["status"] == "success"
+    table_names = [t["table_name"] for t in payload["data"]["tables"]]
+    assert sorted(table_names) == ["frpm", "satscores", "schools"]
+
+
+def test_meta_list_tables_without_schema_uses_default(
+    tmp_path: 'Path', monkeypatch
+) -> None:
+    """meta list-tables without --schema should list tables from default schema."""
+    clear_odps_env(monkeypatch)
+    isolate_home(monkeypatch, tmp_path)
+    import odps
+    monkeypatch.setattr(odps, "ODPS", _SchemaAwareODPS)
+
+    config_path = _make_config_with_odps(tmp_path)
+    code, payload, _ = run_json_command(
+        tmp_path, config_path,
+        ["meta", "list-tables", "--json"],
+    )
+
+    assert code == 0
+    assert payload["status"] == "success"
+    table_names = [t["table_name"] for t in payload["data"]["tables"]]
+    assert sorted(table_names) == ["default_table_a", "default_table_b"]
+
+
+def test_cache_build_passes_schema_to_backend(
+    tmp_path: 'Path', monkeypatch
+) -> None:
+    """cache build --schema should list tables from the specified schema."""
+    clear_odps_env(monkeypatch)
+    isolate_home(monkeypatch, tmp_path)
+    import odps
+    monkeypatch.setattr(odps, "ODPS", _SchemaAwareODPS)
+
+    config_path = _make_config_with_odps(tmp_path)
+    code, payload, _ = run_json_command(
+        tmp_path, config_path,
+        ["cache", "build", "--schema", "california_schools", "--json"],
+    )
+
+    assert code == 0
+    assert payload["data"]["tables_scanned"] == 3
+    assert payload["data"]["cached_tables"] == 3
+
+
+def test_meta_search_passes_schema_to_backend(
+    tmp_path: 'Path', monkeypatch
+) -> None:
+    """meta search --schema should search tables in the specified schema."""
+    clear_odps_env(monkeypatch)
+    isolate_home(monkeypatch, tmp_path)
+    import odps
+    monkeypatch.setattr(odps, "ODPS", _SchemaAwareODPS)
+
+    config_path = _make_config_with_odps(tmp_path)
+    code, payload, _ = run_json_command(
+        tmp_path, config_path,
+        ["meta", "search", "frpm", "--schema", "california_schools", "--json"],
+    )
+
+    assert code == 0
+    assert payload["status"] == "success"
+    matches = payload["data"]["search"]["matches"]
+    assert len(matches) >= 1
+    assert any(m["table_name"] == "frpm" for m in matches)
+
+
+def test_meta_search_columns_passes_schema_to_backend(
+    tmp_path: 'Path', monkeypatch
+) -> None:
+    """meta search-columns --schema should search in the specified schema."""
+    clear_odps_env(monkeypatch)
+    isolate_home(monkeypatch, tmp_path)
+    import odps
+    monkeypatch.setattr(odps, "ODPS", _SchemaAwareODPS)
+
+    config_path = _make_config_with_odps(tmp_path)
+    # search for a keyword that won't match (stub tables have no columns),
+    # but verify it runs without error and uses the right schema
+    code, payload, _ = run_json_command(
+        tmp_path, config_path,
+        ["meta", "search-columns", "nonexistent", "--schema", "california_schools", "--json"],
+    )
+
+    assert code == 0
+    assert payload["status"] == "success"
+    assert payload["data"]["search"]["matches"] == []