> ## Documentation Index
> Fetch the complete documentation index at: https://docs.startree.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Preview a Table From an Uploaded File

> Use multipart upload to infer schema, sample rows, and preview a Pinot table config from a local data file.

Use `POST /tables/previewFromFile` to preview a table from a local file upload. The endpoint accepts a multipart form containing a file and a table-preview request object. It returns inferred schema/config details and sampled rows without creating a table.

<Info>
  Use [`POST /tables/preview`](/api-reference/table/preview) when the source file is already reachable from configured storage or a catalog. Use `previewFromFile` when you need to upload a local file directly to the controller for preview.
</Info>

## Endpoint

```http theme={null}
POST /tables/previewFromFile
Content-Type: multipart/form-data
```

Multipart fields:

| Field     | Required | Type        | Description                                                                                        |
| --------- | -------- | ----------- | -------------------------------------------------------------------------------------------------- |
| `request` | Yes      | JSON string | Serialized `TablePreviewApi` request. Contains table config, optional schema, and preview options. |
| `file`    | Yes      | Binary file | Local sample data file to preview.                                                                 |

The endpoint simulates a table preview with the uploaded file as the source data. It does not persist the file, create a schema, create a table, or ingest rows.

## Basic JSON File Example

Create a request file:

```json theme={null}
{
  "tableConfig": {
    "tableName": "orders_preview",
    "tableType": "OFFLINE",
    "task": {
      "taskTypeConfigsMap": {
        "FileIngestionTask": {
          "inputFormat": "JSON"
        }
      }
    }
  },
  "config": {
    "inference": {
      "schemaInferenceEnabled": true
    }
  }
}
```

Upload a local file:

```bash theme={null}
curl -sS -X POST "https://<controller-host>:9000/tables/previewFromFile" \
  -H "Authorization: Bearer ${TOKEN}" \
  -F 'request=@preview-request.json;type=application/json' \
  -F 'file=@orders.json;type=application/json' | jq
```

## Inline Multipart Example

```bash theme={null}
curl -sS -X POST "https://<controller-host>:9000/tables/previewFromFile" \
  -H "Authorization: Bearer ${TOKEN}" \
  -F 'request={
    "tableConfig": {
      "tableName": "orders_preview",
      "tableType": "OFFLINE",
      "task": {
        "taskTypeConfigsMap": {
          "FileIngestionTask": {
            "inputFormat": "CSV"
          }
        }
      }
    },
    "config": {
      "inference": {
        "schemaInferenceEnabled": true
      }
    }
  };type=application/json' \
  -F 'file=@orders.csv;type=text/csv' | jq
```

## Example Response Shape

The response uses the same preview API shape as `/tables/preview`. Exact fields vary by source type and request options.

```json theme={null}
{
  "tableConfig": {
    "tableName": "orders_preview",
    "tableType": "OFFLINE",
    "segmentsConfig": {
      "schemaName": "orders_preview"
    }
  },
  "schema": {
    "schemaName": "orders_preview",
    "dimensionFieldSpecs": [
      {
        "name": "orderId",
        "dataType": "STRING"
      },
      {
        "name": "status",
        "dataType": "STRING"
      }
    ],
    "metricFieldSpecs": [
      {
        "name": "amount",
        "dataType": "DOUBLE"
      }
    ],
    "dateTimeFieldSpecs": [
      {
        "name": "eventTimeMs",
        "dataType": "TIMESTAMP",
        "format": "1:MILLISECONDS:EPOCH",
        "granularity": "1:MILLISECONDS"
      }
    ]
  },
  "rows": [
    {
      "orderId": "O-1001",
      "status": "COMPLETE",
      "amount": 42.15,
      "eventTimeMs": 1741021200000
    }
  ],
  "summary": {
    "batch": {
      "sampled": 25
    }
  }
}
```

## Request Configuration

At minimum, provide a `tableConfig` with:

* `tableName`
* `tableType`
* `task.taskTypeConfigsMap.FileIngestionTask.inputFormat`

Common `inputFormat` values:

| Format    | File Type                                       |
| --------- | ----------------------------------------------- |
| `JSON`    | Newline-delimited JSON or supported JSON input. |
| `CSV`     | CSV files.                                      |
| `AVRO`    | Avro object container files.                    |
| `PARQUET` | Parquet files.                                  |

Enable schema inference when you want StarTree to infer fields from the uploaded file:

```json theme={null}
{
  "config": {
    "inference": {
      "schemaInferenceEnabled": true
    }
  }
}
```

Provide a schema when you want the preview to validate/sample against a known schema:

```json theme={null}
{
  "schema": {
    "schemaName": "orders_preview",
    "dimensionFieldSpecs": [
      {"name": "orderId", "dataType": "STRING"},
      {"name": "status", "dataType": "STRING"}
    ],
    "metricFieldSpecs": [
      {"name": "amount", "dataType": "DOUBLE"}
    ]
  }
}
```

## Workflow

1. Build a minimal table config and preview config.
2. Upload a representative local file with `POST /tables/previewFromFile`.
3. Inspect inferred schema, sampled rows, and summary.
4. Adjust field names, time column, transforms, and indexes.
5. Use the final schema and table config in the normal table creation flow.

## Limits and Operational Notes

* The endpoint is intended for preview and onboarding workflows, not ingestion.
* Use representative but bounded sample files; do not upload production-scale data files.
* The multipart request must include both `request` and `file`.
* The `request` part must be valid JSON that can deserialize as a table preview request.
* The file format must match the `inputFormat` in the request table task config.

## Troubleshooting

| Symptom                                 | Cause                                                                   | Fix                                                                    |
| --------------------------------------- | ----------------------------------------------------------------------- | ---------------------------------------------------------------------- |
| `Request does not contain table config` | Missing `request` multipart part.                                       | Add the `request` form field with JSON content.                        |
| `Request does not contain file`         | Missing `file` multipart part.                                          | Add the `file` form field with the local sample file.                  |
| `Failed to parse request`               | Request part is not valid JSON or does not match the preview API shape. | Validate the JSON before uploading.                                    |
| `Sampled: 0` or empty rows              | Input format mismatch, parse error, or file has no usable rows.         | Confirm `inputFormat`, file encoding, delimiters, and schema settings. |
| Inferred schema has wrong types         | Sample rows are not representative or values are ambiguous.             | Provide an explicit schema or a better sample file.                    |