# CLI: search

Source: https://mostlyright.md/docs/reference/cli/search/

`mr-data search` has two jobs: read rows from a public table, and prepare search for a table you own. It sends work to the hosted service. No local model or index runs.

## Search public rows

```sh
mr-data public search "games" --json
mr-data public tables DATASET_SLUG --json
mr-data search query PUBLIC_TABLE_ID --query "cooperative games" --page-size 20 --json
```

Use a public table ID returned by `public tables`, not its name or Studio identifier. `public search` finds datasets by their catalog metadata; `search query` searches the rows of one table. Sign in with `mr-data login` for authenticated search.

| Option | Meaning |
| --- | --- |
| `--query TEXT` | Up to 512 characters. A blank query is refused, so the CLI does not browse a table. |
| `--plan FILE` | An explicit `table-search-plan.v2` JSON file. |
| `--unsettled` | Request the typing-time response without the planner. |
| `--cursor CURSOR` | Continue with the previous response's `next_cursor`. |
| `--page-size N` | Bound the requested page. |
| `--count` | Also count matching rows. |
| `--columns a,b` | Choose display columns. |

Read the returned rows, applied plan and timings. Preserve the response's version and cursor when paging. An unavailable index is a failure to handle, not evidence that no rows match. For application code, use the [Search API](/docs/reference/search/) or [JavaScript guide](/docs/guides/javascript/).

## Prepare a new table

Before registration, inspect the recipe without changing it:

```sh
mr-data search inspect --recipe recipe.json --json
mr-data search propose --recipe recipe.json --json
mr-data search validate --recipe recipe.json --json
```

These commands can inspect declared schema before a table exists. They do not prove search quality over real rows. Check the deployment's capability result before adding `table.search`; do not claim unavailable features work.

For an existing table, pass its **Studio table ID**. A sealed version can be selected with `--version TABLE_VERSION_ID`, and a search revision with `--revision SEARCH_REVISION_ID`.

```sh
mr-data search inspect STUDIO_TABLE_ID --json
mr-data search status STUDIO_TABLE_ID --json
```

Search preparation runs independently of the data build. A pending or failed search index does not mean the dataset build failed. Verify both before promising that the table can be searched.

## Manage search revisions

| Operation | Purpose |
| --- | --- |
| `inspect`, `propose` | Inspect declared configuration and propose search intent. |
| `sample`, `values`, `preview` | Read a sealed version through a bounded query. |
| `validate` | Check a spec and evaluation cases before sending them. Accepts `--spec FILE` and `--cases FILE`. |
| `configure`, `add-cases` | Write search configuration or a revision with additional evaluation cases. |
| `locate` | Find the part/row coordinate needed by an evaluation case. |
| `explain`, `estimate` | Inspect a plan or estimate the preparation work. |
| `build` | Start index work and return job coordinates promptly. |
| `status` | Read readiness, job progress and failure details. Accepts `--job JOB_ID`. |
| `evaluate` | Read a revision's measurement state; starts no evaluation. |
| `activate`, `rollback` | Change the active search revision. |
| `cancel` | Cancel the named preparation job. |
| `try` | Test live search with both the Studio table ID and `--public-table PUBLIC_TABLE_ID`. |
| `query` | Read public rows through the same Cloud search route as the dataset page. |

Use `mr-data search OPERATION --help` for that operation's required arguments. Retain the actual version, revision and job identifiers returned by the service. Do not substitute one for another or activate an unverified revision.

The bounded reads wait at most 40 polls and 120 seconds. Repeating the same command reads the same query back. Check the response before starting new work. Test representative queries and expected rows against the observed version; the presence of `table.search` metadata alone is not verification.