# Data commands

Source: /docs/reference/cli/data.md

Use these commands to upload datasets, inspect tables and publications, run read-only SQL analysis, and follow database migration work. The [Data guides](/docs/data) explain these concepts and how they appear in the platform.

## Upload a table [#upload-a-table]

```sh
vortexify upload table ./orders.csv --name orders --wait --json
```

Accepted extensions are CSV, TSV, and XLSX. The path must be a nonempty regular file. `--name` defaults to the filename without its extension. The upload starts asynchronous ingestion and returns a job ID. An explicitly supplied `--name` is used exactly or rejected if an uploaded table with that name already exists; explicit names cannot contain dots or whitespace. Unnamed uploads use the filename stem and add a suffix on collision. To consume an uploaded table named `orders`, use `Table("_upload.orders")`; no connector is needed.

`--wait` waits for ingestion/publication processing. `--timeout` controls that wait, defaulting to 30 minutes; it does not cancel backend ingestion. Key/relationship analysis follows separately. For PDF/TXT/Markdown attachments, see [resource files](/docs/reference/cli/resources#source-documentation-and-agent-attachments).

## List and inspect tables [#list-and-inspect-tables]

```sh
vortexify tables --json
vortexify tables --name orders
vortexify table TABLE_ID --json
vortexify table TABLE_ID --deployed --json
vortexify table TABLE_ID --job PRODUCER_JOB_ID --json
```

| Command / option | Meaning |
| --- | --- |
| `tables` | Project table inventory with source and data/discovery status |
| `tables --name NAME_OR_ID` | Filter by exact name, display name, or ID |
| `table NAME_OR_ID` | Inspect a table's metadata, schema, publication, and analysis progress |
| `table --deployed` | Select the production producer version's output |
| `table --job JOB_ID` | Select a successful publication of that table's producer |
| `--json` | Structured output for scripts and coding agents |

Use an ID when a name matches multiple tables. `--deployed` and `--job` are mutually exclusive. Table inspection reports metadata; it does not print a row preview. Use SQL analysis or the platform Data view for rows. Detailed key/relationship findings are requested by the platform's Relationships view; the CLI currently omits the `include_analysis` selector.

`vortexify tables delete TABLE_ID` soft-deletes an uploaded table. It is a mutation, not an inventory filter, and does not drop a database table.

## Run an analysis query [#run-an-analysis-query]

```sh
vortexify analyze --query-file customer-revenue.sql \
  --table orders=ORDERS_TABLE_ID \
  --table customers=CUSTOMERS_TABLE_ID --wait --json
```

| Option | Behavior |
| --- | --- |
| `--query-file PATH` | Read one SQL SELECT/WITH query from a local file |
| `--table ALIAS=TABLE_ID` | Bind a project table to a SQL alias; repeat for joins |
| `--limit N` | Preview rows, default 20; server allows 1–100 |
| `--deployed` | Use production producer publications for file-backed inputs |
| `--wait` | Wait for the submitted analysis to complete |
| `--json` | Structured result and metadata |
| `--job JOB_ID` | Read an existing analysis instead of submitting a query |

The server accepts 1–10 table aliases and a query up to 32,768 characters. Aliases are SQL identifiers, beginning with a letter or underscore. Use `--job` without query-file or table options:

```sh
vortexify analyze --job ANALYSIS_JOB_ID --json
vortexify analyze --job ANALYSIS_JOB_ID --wait
```

Analysis waiting currently uses a 30-minute client deadline; `analyze` has no configurable `--timeout` flag. You can resume observation with `job JOB_ID --wait --timeout DURATION`. Waiting deadlines do not cancel the analysis worker.

`--limit` affects the preview, while SQL `LIMIT` affects the result. See [Query data with SQL](/docs/data/querying) for a full example, result artifacts, and truncation behavior.

## Inspect and approve database migrations [#inspect-and-approve-database-migrations]

```sh
vortexify database operations --json
vortexify database operations --approve VERSION --environment origin --json
vortexify database operations --reject VERSION --environment origin --json
```

`database` accepts a registered name or ID. Structured status reports environments/applied versions, backups, and approval decisions. The current human-readable formatter expects additional status fields; use structured output for those service records. Review pending SQL through saved source and the database migration service before a decision.

`--approve` and `--reject` require a positive saved version and are mutually exclusive. Approval starts migration work under the database policy and requires project owner/admin access. Follow a returned migration job separately. Approval records the decision; it does not prove SQL succeeded. If migration fails, approving the same saved version again submits a new migration job, while an active job for that version/environment is reused. An empty pending-approval list is not evidence that migration succeeded. Approval responses return public job identity/status without worker host, secret reference, namespace, service account, or bucket configuration. The environment flag selects the decision target (`origin`, the default, or `preview`); it does not create an environment.

Database source/configuration and migrations are covered in [Store app records](/docs/building/store-app-data) and the [database reference](/docs/reference/python/databases).

For ingestion, submitting processing again for the same upload ID reuses active/successful work; failed processing may be submitted again. Running the CLI upload command again creates a new upload ID and remains subject to explicit-name collision checks. Inspect whether the original upload already published before submitting another file.