Preview a Table From an Uploaded 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.

Use POST /tables/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.

Endpoint

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:

{
  "tableConfig": {
    "tableName": "orders_preview",
    "tableType": "OFFLINE",
    "task": {
      "taskTypeConfigsMap": {
        "FileIngestionTask": {
          "inputFormat": "JSON"
        }
      }
    }
  },
  "config": {
    "inference": {
      "schemaInferenceEnabled": true
    }
  }
}

Upload a local file:

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

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.

{
  "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:

{
  "config": {
    "inference": {
      "schemaInferenceEnabled": true
    }
  }
}

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

{
  "schema": {
    "schemaName": "orders_preview",
    "dimensionFieldSpecs": [
      {"name": "orderId", "dataType": "STRING"},
      {"name": "status", "dataType": "STRING"}
    ],
    "metricFieldSpecs": [
      {"name": "amount", "dataType": "DOUBLE"}
    ]
  }
}

Workflow

Build a minimal table config and preview config.
Upload a representative local file with POST /tables/previewFromFile.
Inspect inferred schema, sampled rows, and summary.
Adjust field names, time column, transforms, and indexes.
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.

​Endpoint

​Basic JSON File Example

​Inline Multipart Example

​Example Response Shape

​Request Configuration

​Workflow

​Limits and Operational Notes

​Troubleshooting

Endpoint

Basic JSON File Example

Inline Multipart Example

Example Response Shape

Request Configuration

Workflow

Limits and Operational Notes

Troubleshooting